Initial import from FreeBSD RELENG_4:
[dragonfly.git] / contrib / perl5 / ext / POSIX / 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.  Things which are C<#defines> in C, like EINTR or O_NDELAY, are
23 automatically exported into your namespace.  All functions are only exported
24 if you ask for them explicitly.  Most likely people will prefer to use the
25 fully-qualified function names.
26
27 This document gives a condensed list of the features available in the POSIX
28 module.  Consult your operating system's manpages for general information on
29 most features.  Consult L<perlfunc> for functions which are noted as being
30 identical to Perl's builtin functions.
31
32 The first section describes POSIX functions from the 1003.1 specification.
33 The second section describes some classes for signal objects, TTY objects,
34 and other miscellaneous objects.  The remaining sections list various
35 constants and macros in an organization which roughly follows IEEE Std
36 1003.1b-1993.
37
38 =head1 NOTE
39
40 The POSIX module is probably the most complex Perl module supplied with
41 the standard distribution.  It incorporates autoloading, namespace games,
42 and dynamic loading of code that's in Perl, C, or both.  It's a great
43 source of wisdom.
44
45 =head1 CAVEATS 
46
47 A few functions are not implemented because they are C specific.  If you
48 attempt to call these, they will print a message telling you that they
49 aren't implemented, and suggest using the Perl equivalent should one
50 exist.  For example, trying to access the setjmp() call will elicit the
51 message "setjmp() is C-specific: use eval {} instead".
52
53 Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
54 are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
55 For example, one vendor may not define EDEADLK, or the semantics of the
56 errno values set by open(2) might not be quite right.  Perl does not
57 attempt to verify POSIX compliance.  That means you can currently
58 successfully say "use POSIX",  and then later in your program you find
59 that your vendor has been lax and there's no usable ICANON macro after
60 all.  This could be construed to be a bug.
61
62 =head1 FUNCTIONS
63
64 =over 8
65
66 =item _exit
67
68 This is identical to the C function C<_exit()>.
69
70 =item abort
71
72 This is identical to the C function C<abort()>.
73
74 =item abs
75
76 This is identical to Perl's builtin C<abs()> function.
77
78 =item access
79
80 Determines the accessibility of a file.
81
82         if( POSIX::access( "/", &POSIX::R_OK ) ){
83                 print "have read permission\n";
84         }
85
86 Returns C<undef> on failure.
87
88 =item acos
89
90 This is identical to the C function C<acos()>.
91
92 =item alarm
93
94 This is identical to Perl's builtin C<alarm()> function.
95
96 =item asctime
97
98 This is identical to the C function C<asctime()>.
99
100 =item asin
101
102 This is identical to the C function C<asin()>.
103
104 =item assert
105
106 Unimplemented.
107
108 =item atan
109
110 This is identical to the C function C<atan()>.
111
112 =item atan2
113
114 This is identical to Perl's builtin C<atan2()> function.
115
116 =item atexit
117
118 atexit() is C-specific: use END {} instead.
119
120 =item atof
121
122 atof() is C-specific.
123
124 =item atoi
125
126 atoi() is C-specific.
127
128 =item atol
129
130 atol() is C-specific.
131
132 =item bsearch
133
134 bsearch() not supplied.
135
136 =item calloc
137
138 calloc() is C-specific.
139
140 =item ceil
141
142 This is identical to the C function C<ceil()>.
143
144 =item chdir
145
146 This is identical to Perl's builtin C<chdir()> function.
147
148 =item chmod
149
150 This is identical to Perl's builtin C<chmod()> function.
151
152 =item chown
153
154 This is identical to Perl's builtin C<chown()> function.
155
156 =item clearerr
157
158 Use method C<IO::Handle::clearerr()> instead.
159
160 =item clock
161
162 This is identical to the C function C<clock()>.
163
164 =item close
165
166 Close the file.  This uses file descriptors such as those obtained by calling
167 C<POSIX::open>.
168
169         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
170         POSIX::close( $fd );
171
172 Returns C<undef> on failure.
173
174 =item closedir
175
176 This is identical to Perl's builtin C<closedir()> function.
177
178 =item cos
179
180 This is identical to Perl's builtin C<cos()> function.
181
182 =item cosh
183
184 This is identical to the C function C<cosh()>.
185
186 =item creat
187
188 Create a new file.  This returns a file descriptor like the ones returned by
189 C<POSIX::open>.  Use C<POSIX::close> to close the file.
190
191         $fd = POSIX::creat( "foo", 0611 );
192         POSIX::close( $fd );
193
194 =item ctermid
195
196 Generates the path name for the controlling terminal.
197
198         $path = POSIX::ctermid();
199
200 =item ctime
201
202 This is identical to the C function C<ctime()>.
203
204 =item cuserid
205
206 Get the character login name of the user.
207
208         $name = POSIX::cuserid();
209
210 =item difftime
211
212 This is identical to the C function C<difftime()>.
213
214 =item div
215
216 div() is C-specific.
217
218 =item dup
219
220 This is similar to the C function C<dup()>.
221
222 This uses file descriptors such as those obtained by calling
223 C<POSIX::open>.
224
225 Returns C<undef> on failure.
226
227 =item dup2
228
229 This is similar to the C function C<dup2()>.
230
231 This uses file descriptors such as those obtained by calling
232 C<POSIX::open>.
233
234 Returns C<undef> on failure.
235
236 =item errno
237
238 Returns the value of errno.
239
240         $errno = POSIX::errno();
241
242 =item execl
243
244 execl() is C-specific.
245
246 =item execle
247
248 execle() is C-specific.
249
250 =item execlp
251
252 execlp() is C-specific.
253
254 =item execv
255
256 execv() is C-specific.
257
258 =item execve
259
260 execve() is C-specific.
261
262 =item execvp
263
264 execvp() is C-specific.
265
266 =item exit
267
268 This is identical to Perl's builtin C<exit()> function.
269
270 =item exp
271
272 This is identical to Perl's builtin C<exp()> function.
273
274 =item fabs
275
276 This is identical to Perl's builtin C<abs()> function.
277
278 =item fclose
279
280 Use method C<IO::Handle::close()> instead.
281
282 =item fcntl
283
284 This is identical to Perl's builtin C<fcntl()> function.
285
286 =item fdopen
287
288 Use method C<IO::Handle::new_from_fd()> instead.
289
290 =item feof
291
292 Use method C<IO::Handle::eof()> instead.
293
294 =item ferror
295
296 Use method C<IO::Handle::error()> instead.
297
298 =item fflush
299
300 Use method C<IO::Handle::flush()> instead.
301
302 =item fgetc
303
304 Use method C<IO::Handle::getc()> instead.
305
306 =item fgetpos
307
308 Use method C<IO::Seekable::getpos()> instead.
309
310 =item fgets
311
312 Use method C<IO::Handle::gets()> instead.
313
314 =item fileno
315
316 Use method C<IO::Handle::fileno()> instead.
317
318 =item floor
319
320 This is identical to the C function C<floor()>.
321
322 =item fmod
323
324 This is identical to the C function C<fmod()>.
325
326 =item fopen
327
328 Use method C<IO::File::open()> instead.
329
330 =item fork
331
332 This is identical to Perl's builtin C<fork()> function.
333
334 =item fpathconf
335
336 Retrieves the value of a configurable limit on a file or directory.  This
337 uses file descriptors such as those obtained by calling C<POSIX::open>.
338
339 The following will determine the maximum length of the longest allowable
340 pathname on the filesystem which holds C</tmp/foo>.
341
342         $fd = POSIX::open( "/tmp/foo", &POSIX::O_RDONLY );
343         $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX );
344
345 Returns C<undef> on failure.
346
347 =item fprintf
348
349 fprintf() is C-specific--use printf instead.
350
351 =item fputc
352
353 fputc() is C-specific--use print instead.
354
355 =item fputs
356
357 fputs() is C-specific--use print instead.
358
359 =item fread
360
361 fread() is C-specific--use read instead.
362
363 =item free
364
365 free() is C-specific.
366
367 =item freopen
368
369 freopen() is C-specific--use open instead.
370
371 =item frexp
372
373 Return the mantissa and exponent of a floating-point number.
374
375         ($mantissa, $exponent) = POSIX::frexp( 3.14 );
376
377 =item fscanf
378
379 fscanf() is C-specific--use <> and regular expressions instead.
380
381 =item fseek
382
383 Use method C<IO::Seekable::seek()> instead.
384
385 =item fsetpos
386
387 Use method C<IO::Seekable::setpos()> instead.
388
389 =item fstat
390
391 Get file status.  This uses file descriptors such as those obtained by
392 calling C<POSIX::open>.  The data returned is identical to the data from
393 Perl's builtin C<stat> function.
394
395         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
396         @stats = POSIX::fstat( $fd );
397
398 =item ftell
399
400 Use method C<IO::Seekable::tell()> instead.
401
402 =item fwrite
403
404 fwrite() is C-specific--use print instead.
405
406 =item getc
407
408 This is identical to Perl's builtin C<getc()> function.
409
410 =item getchar
411
412 Returns one character from STDIN.
413
414 =item getcwd
415
416 Returns the name of the current working directory.
417
418 =item getegid
419
420 Returns the effective group id.
421
422 =item getenv
423
424 Returns the value of the specified enironment variable.
425
426 =item geteuid
427
428 Returns the effective user id.
429
430 =item getgid
431
432 Returns the user's real group id.
433
434 =item getgrgid
435
436 This is identical to Perl's builtin C<getgrgid()> function.
437
438 =item getgrnam
439
440 This is identical to Perl's builtin C<getgrnam()> function.
441
442 =item getgroups
443
444 Returns the ids of the user's supplementary groups.
445
446 =item getlogin
447
448 This is identical to Perl's builtin C<getlogin()> function.
449
450 =item getpgrp
451
452 This is identical to Perl's builtin C<getpgrp()> function.
453
454 =item getpid
455
456 Returns the process's id.
457
458 =item getppid
459
460 This is identical to Perl's builtin C<getppid()> function.
461
462 =item getpwnam
463
464 This is identical to Perl's builtin C<getpwnam()> function.
465
466 =item getpwuid
467
468 This is identical to Perl's builtin C<getpwuid()> function.
469
470 =item gets
471
472 Returns one line from STDIN.
473
474 =item getuid
475
476 Returns the user's id.
477
478 =item gmtime
479
480 This is identical to Perl's builtin C<gmtime()> function.
481
482 =item isalnum
483
484 This is identical to the C function, except that it can apply to a single
485 character or to a whole string.
486
487 =item isalpha
488
489 This is identical to the C function, except that it can apply to a single
490 character or to a whole string.
491
492 =item isatty
493
494 Returns a boolean indicating whether the specified filehandle is connected
495 to a tty.
496
497 =item iscntrl
498
499 This is identical to the C function, except that it can apply to a single
500 character or to a whole string.
501
502 =item isdigit
503
504 This is identical to the C function, except that it can apply to a single
505 character or to a whole string.
506
507 =item isgraph
508
509 This is identical to the C function, except that it can apply to a single
510 character or to a whole string.
511
512 =item islower
513
514 This is identical to the C function, except that it can apply to a single
515 character or to a whole string.
516
517 =item isprint
518
519 This is identical to the C function, except that it can apply to a single
520 character or to a whole string.
521
522 =item ispunct
523
524 This is identical to the C function, except that it can apply to a single
525 character or to a whole string.
526
527 =item isspace
528
529 This is identical to the C function, except that it can apply to a single
530 character or to a whole string.
531
532 =item isupper
533
534 This is identical to the C function, except that it can apply to a single
535 character or to a whole string.
536
537 =item isxdigit
538
539 This is identical to the C function, except that it can apply to a single
540 character or to a whole string.
541
542 =item kill
543
544 This is identical to Perl's builtin C<kill()> function.
545
546 =item labs
547
548 labs() is C-specific, use abs instead.
549
550 =item ldexp
551
552 This is identical to the C function C<ldexp()>.
553
554 =item ldiv
555
556 ldiv() is C-specific, use / and int instead.
557
558 =item link
559
560 This is identical to Perl's builtin C<link()> function.
561
562 =item localeconv
563
564 Get numeric formatting information.  Returns a reference to a hash
565 containing the current locale formatting values.
566
567 The database for the B<de> (Deutsch or German) locale.
568
569         $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
570         print "Locale = $loc\n";
571         $lconv = POSIX::localeconv();
572         print "decimal_point    = ", $lconv->{decimal_point},   "\n";
573         print "thousands_sep    = ", $lconv->{thousands_sep},   "\n";
574         print "grouping = ", $lconv->{grouping},        "\n";
575         print "int_curr_symbol  = ", $lconv->{int_curr_symbol}, "\n";
576         print "currency_symbol  = ", $lconv->{currency_symbol}, "\n";
577         print "mon_decimal_point = ", $lconv->{mon_decimal_point}, "\n";
578         print "mon_thousands_sep = ", $lconv->{mon_thousands_sep}, "\n";
579         print "mon_grouping     = ", $lconv->{mon_grouping},    "\n";
580         print "positive_sign    = ", $lconv->{positive_sign},   "\n";
581         print "negative_sign    = ", $lconv->{negative_sign},   "\n";
582         print "int_frac_digits  = ", $lconv->{int_frac_digits}, "\n";
583         print "frac_digits      = ", $lconv->{frac_digits},     "\n";
584         print "p_cs_precedes    = ", $lconv->{p_cs_precedes},   "\n";
585         print "p_sep_by_space   = ", $lconv->{p_sep_by_space},  "\n";
586         print "n_cs_precedes    = ", $lconv->{n_cs_precedes},   "\n";
587         print "n_sep_by_space   = ", $lconv->{n_sep_by_space},  "\n";
588         print "p_sign_posn      = ", $lconv->{p_sign_posn},     "\n";
589         print "n_sign_posn      = ", $lconv->{n_sign_posn},     "\n";
590
591 =item localtime
592
593 This is identical to Perl's builtin C<localtime()> function.
594
595 =item log
596
597 This is identical to Perl's builtin C<log()> function.
598
599 =item log10
600
601 This is identical to the C function C<log10()>.
602
603 =item longjmp
604
605 longjmp() is C-specific: use die instead.
606
607 =item lseek
608
609 Move the file's read/write position.  This uses file descriptors such as
610 those obtained by calling C<POSIX::open>.
611
612         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
613         $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
614
615 Returns C<undef> on failure.
616
617 =item malloc
618
619 malloc() is C-specific.
620
621 =item mblen
622
623 This is identical to the C function C<mblen()>.
624
625 =item mbstowcs
626
627 This is identical to the C function C<mbstowcs()>.
628
629 =item mbtowc
630
631 This is identical to the C function C<mbtowc()>.
632
633 =item memchr
634
635 memchr() is C-specific, use index() instead.
636
637 =item memcmp
638
639 memcmp() is C-specific, use eq instead.
640
641 =item memcpy
642
643 memcpy() is C-specific, use = instead.
644
645 =item memmove
646
647 memmove() is C-specific, use = instead.
648
649 =item memset
650
651 memset() is C-specific, use x instead.
652
653 =item mkdir
654
655 This is identical to Perl's builtin C<mkdir()> function.
656
657 =item mkfifo
658
659 This is similar to the C function C<mkfifo()>.
660
661 Returns C<undef> on failure.
662
663 =item mktime
664
665 Convert date/time info to a calendar time.
666
667 Synopsis:
668
669         mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0)
670
671 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
672 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
673 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
674 year 2001 is 101.  Consult your system's C<mktime()> manpage for details
675 about these and the other arguments.
676
677 Calendar time for December 12, 1995, at 10:30 am.
678
679         $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
680         print "Date = ", POSIX::ctime($time_t);
681
682 Returns C<undef> on failure.
683
684 =item modf
685
686 Return the integral and fractional parts of a floating-point number.
687
688         ($fractional, $integral) = POSIX::modf( 3.14 );
689
690 =item nice
691
692 This is similar to the C function C<nice()>.
693
694 Returns C<undef> on failure.
695
696 =item offsetof
697
698 offsetof() is C-specific.
699
700 =item open
701
702 Open a file for reading for writing.  This returns file descriptors, not
703 Perl filehandles.  Use C<POSIX::close> to close the file.
704
705 Open a file read-only with mode 0666.
706
707         $fd = POSIX::open( "foo" );
708
709 Open a file for read and write.
710
711         $fd = POSIX::open( "foo", &POSIX::O_RDWR );
712
713 Open a file for write, with truncation.
714
715         $fd = POSIX::open( "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC );
716
717 Create a new file with mode 0640.  Set up the file for writing.
718
719         $fd = POSIX::open( "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640 );
720
721 Returns C<undef> on failure.
722
723 =item opendir
724
725 Open a directory for reading.
726
727         $dir = POSIX::opendir( "/tmp" );
728         @files = POSIX::readdir( $dir );
729         POSIX::closedir( $dir );
730
731 Returns C<undef> on failure.
732
733 =item pathconf
734
735 Retrieves the value of a configurable limit on a file or directory.
736
737 The following will determine the maximum length of the longest allowable
738 pathname on the filesystem which holds C</tmp>.
739
740         $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX );
741
742 Returns C<undef> on failure.
743
744 =item pause
745
746 This is similar to the C function C<pause()>.
747
748 Returns C<undef> on failure.
749
750 =item perror
751
752 This is identical to the C function C<perror()>.
753
754 =item pipe
755
756 Create an interprocess channel.  This returns file descriptors like those
757 returned by C<POSIX::open>.
758
759         ($fd0, $fd1) = POSIX::pipe();
760         POSIX::write( $fd0, "hello", 5 );
761         POSIX::read( $fd1, $buf, 5 );
762
763 =item pow
764
765 Computes $x raised to the power $exponent.
766
767         $ret = POSIX::pow( $x, $exponent );
768
769 =item printf
770
771 Prints the specified arguments to STDOUT.
772
773 =item putc
774
775 putc() is C-specific--use print instead.
776
777 =item putchar
778
779 putchar() is C-specific--use print instead.
780
781 =item puts
782
783 puts() is C-specific--use print instead.
784
785 =item qsort
786
787 qsort() is C-specific, use sort instead.
788
789 =item raise
790
791 Sends the specified signal to the current process.
792
793 =item rand
794
795 rand() is non-portable, use Perl's rand instead.
796
797 =item read
798
799 Read from a file.  This uses file descriptors such as those obtained by
800 calling C<POSIX::open>.  If the buffer C<$buf> is not large enough for the
801 read then Perl will extend it to make room for the request.
802
803         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
804         $bytes = POSIX::read( $fd, $buf, 3 );
805
806 Returns C<undef> on failure.
807
808 =item readdir
809
810 This is identical to Perl's builtin C<readdir()> function.
811
812 =item realloc
813
814 realloc() is C-specific.
815
816 =item remove
817
818 This is identical to Perl's builtin C<unlink()> function.
819
820 =item rename
821
822 This is identical to Perl's builtin C<rename()> function.
823
824 =item rewind
825
826 Seeks to the beginning of the file.
827
828 =item rewinddir
829
830 This is identical to Perl's builtin C<rewinddir()> function.
831
832 =item rmdir
833
834 This is identical to Perl's builtin C<rmdir()> function.
835
836 =item scanf
837
838 scanf() is C-specific--use <> and regular expressions instead.
839
840 =item setgid
841
842 Sets the real group id for this process.
843
844 =item setjmp
845
846 setjmp() is C-specific: use eval {} instead.
847
848 =item setlocale
849
850 Modifies and queries program's locale.
851
852 The following will set the traditional UNIX system locale behavior
853 (the second argument C<"C">).
854
855         $loc = POSIX::setlocale( &POSIX::LC_ALL, "C" );
856
857 The following will query (the missing second argument) the current
858 LC_CTYPE category.
859
860         $loc = POSIX::setlocale( &POSIX::LC_CTYPE);
861
862 The following will set the LC_CTYPE behaviour according to the locale
863 environment variables (the second argument C<"">).
864 Please see your systems L<setlocale(3)> documentation for the locale
865 environment variables' meaning or consult L<perllocale>.
866
867         $loc = POSIX::setlocale( &POSIX::LC_CTYPE, "");
868
869 The following will set the LC_COLLATE behaviour to Argentinian
870 Spanish. B<NOTE>: The naming and availability of locales depends on
871 your operating system. Please consult L<perllocale> for how to find
872 out which locales are available in your system.
873
874         $loc = POSIX::setlocale( &POSIX::LC_ALL, "es_AR.ISO8859-1" );
875
876 =item setpgid
877
878 This is similar to the C function C<setpgid()>.
879
880 Returns C<undef> on failure.
881
882 =item setsid
883
884 This is identical to the C function C<setsid()>.
885
886 =item setuid
887
888 Sets the real user id for this process.
889
890 =item sigaction
891
892 Detailed signal management.  This uses C<POSIX::SigAction> objects for the
893 C<action> and C<oldaction> arguments.  Consult your system's C<sigaction>
894 manpage for details.
895
896 Synopsis:
897
898         sigaction(sig, action, oldaction = 0)
899
900 Returns C<undef> on failure.
901
902 =item siglongjmp
903
904 siglongjmp() is C-specific: use die instead.
905
906 =item sigpending
907
908 Examine signals that are blocked and pending.  This uses C<POSIX::SigSet>
909 objects for the C<sigset> argument.  Consult your system's C<sigpending>
910 manpage for details.
911
912 Synopsis:
913
914         sigpending(sigset)
915
916 Returns C<undef> on failure.
917
918 =item sigprocmask
919
920 Change and/or examine calling process's signal mask.  This uses
921 C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
922 Consult your system's C<sigprocmask> manpage for details.
923
924 Synopsis:
925
926         sigprocmask(how, sigset, oldsigset = 0)
927
928 Returns C<undef> on failure.
929
930 =item sigsetjmp
931
932 sigsetjmp() is C-specific: use eval {} instead.
933
934 =item sigsuspend
935
936 Install a signal mask and suspend process until signal arrives.  This uses
937 C<POSIX::SigSet> objects for the C<signal_mask> argument.  Consult your
938 system's C<sigsuspend> manpage for details.
939
940 Synopsis:
941
942         sigsuspend(signal_mask)
943
944 Returns C<undef> on failure.
945
946 =item sin
947
948 This is identical to Perl's builtin C<sin()> function.
949
950 =item sinh
951
952 This is identical to the C function C<sinh()>.
953
954 =item sleep
955
956 This is identical to Perl's builtin C<sleep()> function.
957
958 =item sprintf
959
960 This is identical to Perl's builtin C<sprintf()> function.
961
962 =item sqrt
963
964 This is identical to Perl's builtin C<sqrt()> function.
965
966 =item srand
967
968 srand().
969
970 =item sscanf
971
972 sscanf() is C-specific--use regular expressions instead.
973
974 =item stat
975
976 This is identical to Perl's builtin C<stat()> function.
977
978 =item strcat
979
980 strcat() is C-specific, use .= instead.
981
982 =item strchr
983
984 strchr() is C-specific, use index() instead.
985
986 =item strcmp
987
988 strcmp() is C-specific, use eq instead.
989
990 =item strcoll
991
992 This is identical to the C function C<strcoll()>.
993
994 =item strcpy
995
996 strcpy() is C-specific, use = instead.
997
998 =item strcspn
999
1000 strcspn() is C-specific, use regular expressions instead.
1001
1002 =item strerror
1003
1004 Returns the error string for the specified errno.
1005
1006 =item strftime
1007
1008 Convert date and time information to string.  Returns the string.
1009
1010 Synopsis:
1011
1012         strftime(fmt, sec, min, hour, mday, mon, year, wday = -1, yday = -1, isdst = -1)
1013
1014 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
1015 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
1016 year (C<year>) is given in years since 1900.  I.e., the year 1995 is 95; the
1017 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
1018 about these and the other arguments.  The given arguments are made consistent
1019 by calling C<mktime()> before calling your system's C<strftime()> function.
1020
1021 The string for Tuesday, December 12, 1995.
1022
1023         $str = POSIX::strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2 );
1024         print "$str\n";
1025
1026 =item strlen
1027
1028 strlen() is C-specific, use length instead.
1029
1030 =item strncat
1031
1032 strncat() is C-specific, use .= instead.
1033
1034 =item strncmp
1035
1036 strncmp() is C-specific, use eq instead.
1037
1038 =item strncpy
1039
1040 strncpy() is C-specific, use = instead.
1041
1042 =item stroul
1043
1044 stroul() is C-specific.
1045
1046 =item strpbrk
1047
1048 strpbrk() is C-specific.
1049
1050 =item strrchr
1051
1052 strrchr() is C-specific, use rindex() instead.
1053
1054 =item strspn
1055
1056 strspn() is C-specific.
1057
1058 =item strstr
1059
1060 This is identical to Perl's builtin C<index()> function.
1061
1062 =item strtod
1063
1064 String to double translation. Returns the parsed number and the number
1065 of characters in the unparsed portion of the string.  Truly
1066 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1067 error, so clear $! before calling strtod.  However, non-POSIX systems
1068 may not check for overflow, and therefore will never set $!.
1069
1070 strtod should respect any POSIX I<setlocale()> settings.
1071
1072 To parse a string $str as a floating point number use
1073
1074     $! = 0;
1075     ($num, $n_unparsed) = POSIX::strtod($str);
1076
1077 The second returned item and $! can be used to check for valid input:
1078
1079     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1080         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1081     }
1082
1083 When called in a scalar context strtod returns the parsed number.
1084
1085 =item strtok
1086
1087 strtok() is C-specific.
1088
1089 =item strtol
1090
1091 String to (long) integer translation.  Returns the parsed number and
1092 the number of characters in the unparsed portion of the string.  Truly
1093 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1094 error, so clear $! before calling strtol.  However, non-POSIX systems
1095 may not check for overflow, and therefore will never set $!.
1096
1097 strtol should respect any POSIX I<setlocale()> settings.
1098
1099 To parse a string $str as a number in some base $base use
1100
1101     $! = 0;
1102     ($num, $n_unparsed) = POSIX::strtol($str, $base);
1103
1104 The base should be zero or between 2 and 36, inclusive.  When the base
1105 is zero or omitted strtol will use the string itself to determine the
1106 base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1107 octal; any other leading characters mean decimal.  Thus, "1234" is
1108 parsed as a decimal number, "01234" as an octal number, and "0x1234"
1109 as a hexadecimal number.
1110
1111 The second returned item and $! can be used to check for valid input:
1112
1113     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1114         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1115     }
1116
1117 When called in a scalar context strtol returns the parsed number.
1118
1119 =item strtoul
1120
1121 String to unsigned (long) integer translation.  strtoul is identical
1122 to strtol except that strtoul only parses unsigned integers.  See
1123 I<strtol> for details.
1124
1125 Note: Some vendors supply strtod and strtol but not strtoul.
1126 Other vendors that do suply strtoul parse "-1" as a valid value.
1127
1128 =item strxfrm
1129
1130 String transformation.  Returns the transformed string.
1131
1132         $dst = POSIX::strxfrm( $src );
1133
1134 =item sysconf
1135
1136 Retrieves values of system configurable variables.
1137
1138 The following will get the machine's clock speed.
1139
1140         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1141
1142 Returns C<undef> on failure.
1143
1144 =item system
1145
1146 This is identical to Perl's builtin C<system()> function.
1147
1148 =item tan
1149
1150 This is identical to the C function C<tan()>.
1151
1152 =item tanh
1153
1154 This is identical to the C function C<tanh()>.
1155
1156 =item tcdrain
1157
1158 This is similar to the C function C<tcdrain()>.
1159
1160 Returns C<undef> on failure.
1161
1162 =item tcflow
1163
1164 This is similar to the C function C<tcflow()>.
1165
1166 Returns C<undef> on failure.
1167
1168 =item tcflush
1169
1170 This is similar to the C function C<tcflush()>.
1171
1172 Returns C<undef> on failure.
1173
1174 =item tcgetpgrp
1175
1176 This is identical to the C function C<tcgetpgrp()>.
1177
1178 =item tcsendbreak
1179
1180 This is similar to the C function C<tcsendbreak()>.
1181
1182 Returns C<undef> on failure.
1183
1184 =item tcsetpgrp
1185
1186 This is similar to the C function C<tcsetpgrp()>.
1187
1188 Returns C<undef> on failure.
1189
1190 =item time
1191
1192 This is identical to Perl's builtin C<time()> function.
1193
1194 =item times
1195
1196 The times() function returns elapsed realtime since some point in the past
1197 (such as system startup), user and system times for this process, and user
1198 and system times used by child processes.  All times are returned in clock
1199 ticks.
1200
1201     ($realtime, $user, $system, $cuser, $csystem) = POSIX::times();
1202
1203 Note: Perl's builtin C<times()> function returns four values, measured in
1204 seconds.
1205
1206 =item tmpfile
1207
1208 Use method C<IO::File::new_tmpfile()> instead.
1209
1210 =item tmpnam
1211
1212 Returns a name for a temporary file.
1213
1214         $tmpfile = POSIX::tmpnam();
1215
1216 =item tolower
1217
1218 This is identical to Perl's builtin C<lc()> function.
1219
1220 =item toupper
1221
1222 This is identical to Perl's builtin C<uc()> function.
1223
1224 =item ttyname
1225
1226 This is identical to the C function C<ttyname()>.
1227
1228 =item tzname
1229
1230 Retrieves the time conversion information from the C<tzname> variable.
1231
1232         POSIX::tzset();
1233         ($std, $dst) = POSIX::tzname();
1234
1235 =item tzset
1236
1237 This is identical to the C function C<tzset()>.
1238
1239 =item umask
1240
1241 This is identical to Perl's builtin C<umask()> function.
1242
1243 =item uname
1244
1245 Get name of current operating system.
1246
1247         ($sysname, $nodename, $release, $version, $machine ) = POSIX::uname();
1248
1249 =item ungetc
1250
1251 Use method C<IO::Handle::ungetc()> instead.
1252
1253 =item unlink
1254
1255 This is identical to Perl's builtin C<unlink()> function.
1256
1257 =item utime
1258
1259 This is identical to Perl's builtin C<utime()> function.
1260
1261 =item vfprintf
1262
1263 vfprintf() is C-specific.
1264
1265 =item vprintf
1266
1267 vprintf() is C-specific.
1268
1269 =item vsprintf
1270
1271 vsprintf() is C-specific.
1272
1273 =item wait
1274
1275 This is identical to Perl's builtin C<wait()> function.
1276
1277 =item waitpid
1278
1279 Wait for a child process to change state.  This is identical to Perl's
1280 builtin C<waitpid()> function.
1281
1282         $pid = POSIX::waitpid( -1, &POSIX::WNOHANG );
1283         print "status = ", ($? / 256), "\n";
1284
1285 =item wcstombs
1286
1287 This is identical to the C function C<wcstombs()>.
1288
1289 =item wctomb
1290
1291 This is identical to the C function C<wctomb()>.
1292
1293 =item write
1294
1295 Write to a file.  This uses file descriptors such as those obtained by
1296 calling C<POSIX::open>.
1297
1298         $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
1299         $buf = "hello";
1300         $bytes = POSIX::write( $b, $buf, 5 );
1301
1302 Returns C<undef> on failure.
1303
1304 =back
1305
1306 =head1 CLASSES
1307
1308 =head2 POSIX::SigAction
1309
1310 =over 8
1311
1312 =item new
1313
1314 Creates a new C<POSIX::SigAction> object which corresponds to the C
1315 C<struct sigaction>.  This object will be destroyed automatically when it is
1316 no longer needed.  The first parameter is the fully-qualified name of a sub
1317 which is a signal-handler.  The second parameter is a C<POSIX::SigSet>
1318 object, it defaults to the empty set.  The third parameter contains the
1319 C<sa_flags>, it defaults to 0.
1320
1321         $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
1322         $sigaction = POSIX::SigAction->new( 'main::handler', $sigset, &POSIX::SA_NOCLDSTOP );
1323
1324 This C<POSIX::SigAction> object should be used with the C<POSIX::sigaction()>
1325 function.
1326
1327 =back
1328
1329 =head2 POSIX::SigSet
1330
1331 =over 8
1332
1333 =item new
1334
1335 Create a new SigSet object.  This object will be destroyed automatically
1336 when it is no longer needed.  Arguments may be supplied to initialize the
1337 set.
1338
1339 Create an empty set.
1340
1341         $sigset = POSIX::SigSet->new;
1342
1343 Create a set with SIGUSR1.
1344
1345         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
1346
1347 =item addset
1348
1349 Add a signal to a SigSet object.
1350
1351         $sigset->addset( &POSIX::SIGUSR2 );
1352
1353 Returns C<undef> on failure.
1354
1355 =item delset
1356
1357 Remove a signal from the SigSet object.
1358
1359         $sigset->delset( &POSIX::SIGUSR2 );
1360
1361 Returns C<undef> on failure.
1362
1363 =item emptyset
1364
1365 Initialize the SigSet object to be empty.
1366
1367         $sigset->emptyset();
1368
1369 Returns C<undef> on failure.
1370
1371 =item fillset
1372
1373 Initialize the SigSet object to include all signals.
1374
1375         $sigset->fillset();
1376
1377 Returns C<undef> on failure.
1378
1379 =item ismember
1380
1381 Tests the SigSet object to see if it contains a specific signal.
1382
1383         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
1384                 print "contains SIGUSR1\n";
1385         }
1386
1387 =back
1388
1389 =head2 POSIX::Termios
1390
1391 =over 8
1392
1393 =item new
1394
1395 Create a new Termios object.  This object will be destroyed automatically
1396 when it is no longer needed.  A Termios object corresponds to the termios
1397 C struct.  new() mallocs a new one, getattr() fills it from a file descriptor,
1398 and setattr() sets a file descriptor's parameters to match Termios' contents.
1399
1400         $termios = POSIX::Termios->new;
1401
1402 =item getattr
1403
1404 Get terminal control attributes.
1405
1406 Obtain the attributes for stdin.
1407
1408         $termios->getattr()
1409
1410 Obtain the attributes for stdout.
1411
1412         $termios->getattr( 1 )
1413
1414 Returns C<undef> on failure.
1415
1416 =item getcc
1417
1418 Retrieve a value from the c_cc field of a termios object.  The c_cc field is
1419 an array so an index must be specified.
1420
1421         $c_cc[1] = $termios->getcc(1);
1422
1423 =item getcflag
1424
1425 Retrieve the c_cflag field of a termios object.
1426
1427         $c_cflag = $termios->getcflag;
1428
1429 =item getiflag
1430
1431 Retrieve the c_iflag field of a termios object.
1432
1433         $c_iflag = $termios->getiflag;
1434
1435 =item getispeed
1436
1437 Retrieve the input baud rate.
1438
1439         $ispeed = $termios->getispeed;
1440
1441 =item getlflag
1442
1443 Retrieve the c_lflag field of a termios object.
1444
1445         $c_lflag = $termios->getlflag;
1446
1447 =item getoflag
1448
1449 Retrieve the c_oflag field of a termios object.
1450
1451         $c_oflag = $termios->getoflag;
1452
1453 =item getospeed
1454
1455 Retrieve the output baud rate.
1456
1457         $ospeed = $termios->getospeed;
1458
1459 =item setattr
1460
1461 Set terminal control attributes.
1462
1463 Set attributes immediately for stdout.
1464
1465         $termios->setattr( 1, &POSIX::TCSANOW );
1466
1467 Returns C<undef> on failure.
1468
1469 =item setcc
1470
1471 Set a value in the c_cc field of a termios object.  The c_cc field is an
1472 array so an index must be specified.
1473
1474         $termios->setcc( &POSIX::VEOF, 1 );
1475
1476 =item setcflag
1477
1478 Set the c_cflag field of a termios object.
1479
1480         $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
1481
1482 =item setiflag
1483
1484 Set the c_iflag field of a termios object.
1485
1486         $termios->setiflag( $c_iflag | &POSIX::BRKINT );
1487
1488 =item setispeed
1489
1490 Set the input baud rate.
1491
1492         $termios->setispeed( &POSIX::B9600 );
1493
1494 Returns C<undef> on failure.
1495
1496 =item setlflag
1497
1498 Set the c_lflag field of a termios object.
1499
1500         $termios->setlflag( $c_lflag | &POSIX::ECHO );
1501
1502 =item setoflag
1503
1504 Set the c_oflag field of a termios object.
1505
1506         $termios->setoflag( $c_oflag | &POSIX::OPOST );
1507
1508 =item setospeed
1509
1510 Set the output baud rate.
1511
1512         $termios->setospeed( &POSIX::B9600 );
1513
1514 Returns C<undef> on failure.
1515
1516 =item Baud rate values
1517
1518 B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110
1519
1520 =item Terminal interface values
1521
1522 TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF
1523
1524 =item c_cc field values
1525
1526 VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS
1527
1528 =item c_cflag field values
1529
1530 CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD
1531
1532 =item c_iflag field values
1533
1534 BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK
1535
1536 =item c_lflag field values
1537
1538 ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP
1539
1540 =item c_oflag field values
1541
1542 OPOST
1543
1544 =back
1545
1546 =head1 PATHNAME CONSTANTS
1547
1548 =over 8
1549
1550 =item Constants
1551
1552 _PC_CHOWN_RESTRICTED _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX _PC_NO_TRUNC _PC_PATH_MAX _PC_PIPE_BUF _PC_VDISABLE
1553
1554 =back
1555
1556 =head1 POSIX CONSTANTS
1557
1558 =over 8
1559
1560 =item Constants
1561
1562 _POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL _POSIX_LINK_MAX _POSIX_MAX_CANON _POSIX_MAX_INPUT _POSIX_NAME_MAX _POSIX_NGROUPS_MAX _POSIX_NO_TRUNC _POSIX_OPEN_MAX _POSIX_PATH_MAX _POSIX_PIPE_BUF _POSIX_SAVED_IDS _POSIX_SSIZE_MAX _POSIX_STREAM_MAX _POSIX_TZNAME_MAX _POSIX_VDISABLE _POSIX_VERSION
1563
1564 =back
1565
1566 =head1 SYSTEM CONFIGURATION
1567
1568 =over 8
1569
1570 =item Constants
1571
1572 _SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION
1573
1574 =back
1575
1576 =head1 ERRNO
1577
1578 =over 8
1579
1580 =item Constants
1581
1582 E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
1583 EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ
1584 EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR
1585 EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG
1586 ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC
1587 ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR
1588 ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE
1589 EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS
1590 ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS
1591 ETXTBSY EUSERS EWOULDBLOCK EXDEV
1592
1593 =back
1594
1595 =head1 FCNTL
1596
1597 =over 8
1598
1599 =item Constants
1600
1601 FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_OK F_RDLCK F_SETFD F_SETFL F_SETLK F_SETLKW F_UNLCK F_WRLCK O_ACCMODE O_APPEND O_CREAT O_EXCL O_NOCTTY O_NONBLOCK O_RDONLY O_RDWR O_TRUNC O_WRONLY
1602
1603 =back
1604
1605 =head1 FLOAT
1606
1607 =over 8
1608
1609 =item Constants
1610
1611 DBL_DIG DBL_EPSILON DBL_MANT_DIG DBL_MAX DBL_MAX_10_EXP DBL_MAX_EXP DBL_MIN DBL_MIN_10_EXP DBL_MIN_EXP FLT_DIG FLT_EPSILON FLT_MANT_DIG FLT_MAX FLT_MAX_10_EXP FLT_MAX_EXP FLT_MIN FLT_MIN_10_EXP FLT_MIN_EXP FLT_RADIX FLT_ROUNDS LDBL_DIG LDBL_EPSILON LDBL_MANT_DIG LDBL_MAX LDBL_MAX_10_EXP LDBL_MAX_EXP LDBL_MIN LDBL_MIN_10_EXP LDBL_MIN_EXP
1612
1613 =back
1614
1615 =head1 LIMITS
1616
1617 =over 8
1618
1619 =item Constants
1620
1621 ARG_MAX CHAR_BIT CHAR_MAX CHAR_MIN CHILD_MAX INT_MAX INT_MIN LINK_MAX LONG_MAX LONG_MIN MAX_CANON MAX_INPUT MB_LEN_MAX NAME_MAX NGROUPS_MAX OPEN_MAX PATH_MAX PIPE_BUF SCHAR_MAX SCHAR_MIN SHRT_MAX SHRT_MIN SSIZE_MAX STREAM_MAX TZNAME_MAX UCHAR_MAX UINT_MAX ULONG_MAX USHRT_MAX
1622
1623 =back
1624
1625 =head1 LOCALE
1626
1627 =over 8
1628
1629 =item Constants
1630
1631 LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
1632
1633 =back
1634
1635 =head1 MATH
1636
1637 =over 8
1638
1639 =item Constants
1640
1641 HUGE_VAL
1642
1643 =back
1644
1645 =head1 SIGNAL
1646
1647 =over 8
1648
1649 =item Constants
1650
1651 SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART
1652 SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT
1653 SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU
1654 SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK
1655 SIG_UNBLOCK
1656
1657 =back
1658
1659 =head1 STAT
1660
1661 =over 8
1662
1663 =item Constants
1664
1665 S_IRGRP S_IROTH S_IRUSR S_IRWXG S_IRWXO S_IRWXU S_ISGID S_ISUID S_IWGRP S_IWOTH S_IWUSR S_IXGRP S_IXOTH S_IXUSR
1666
1667 =item Macros
1668
1669 S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG
1670
1671 =back
1672
1673 =head1 STDLIB
1674
1675 =over 8
1676
1677 =item Constants
1678
1679 EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX
1680
1681 =back
1682
1683 =head1 STDIO
1684
1685 =over 8
1686
1687 =item Constants
1688
1689 BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX
1690
1691 =back
1692
1693 =head1 TIME
1694
1695 =over 8
1696
1697 =item Constants
1698
1699 CLK_TCK CLOCKS_PER_SEC
1700
1701 =back
1702
1703 =head1 UNISTD
1704
1705 =over 8
1706
1707 =item Constants
1708
1709 R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STRERR_FILENO W_OK X_OK
1710
1711 =back
1712
1713 =head1 WAIT
1714
1715 =over 8
1716
1717 =item Constants
1718
1719 WNOHANG WUNTRACED
1720
1721 =item Macros
1722
1723 WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
1724
1725 =back
1726
1727 =head1 CREATION
1728
1729 This document generated by ./mkposixman.PL version 19960129.
1730