This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
applied patch, moved #define mkfifo ... from perl.h to POSIX.xs
[perl5.git] / 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 mknod
664
665 This is similar to the C function C<mknod()>.
666
667 Returns C<undef> on failure.
668
669 =item mktime
670
671 Convert date/time info to a calendar time.
672
673 Synopsis:
674
675         mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0)
676
677 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
678 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
679 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
680 year 2001 is 101.  Consult your system's C<mktime()> manpage for details
681 about these and the other arguments.
682
683 Calendar time for December 12, 1995, at 10:30 am.
684
685         $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
686         print "Date = ", POSIX::ctime($time_t);
687
688 Returns C<undef> on failure.
689
690 =item modf
691
692 Return the integral and fractional parts of a floating-point number.
693
694         ($fractional, $integral) = POSIX::modf( 3.14 );
695
696 =item nice
697
698 This is similar to the C function C<nice()>.
699
700 Returns C<undef> on failure.
701
702 =item offsetof
703
704 offsetof() is C-specific.
705
706 =item open
707
708 Open a file for reading for writing.  This returns file descriptors, not
709 Perl filehandles.  Use C<POSIX::close> to close the file.
710
711 Open a file read-only with mode 0666.
712
713         $fd = POSIX::open( "foo" );
714
715 Open a file for read and write.
716
717         $fd = POSIX::open( "foo", &POSIX::O_RDWR );
718
719 Open a file for write, with truncation.
720
721         $fd = POSIX::open( "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC );
722
723 Create a new file with mode 0640.  Set up the file for writing.
724
725         $fd = POSIX::open( "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640 );
726
727 Returns C<undef> on failure.
728
729 =item opendir
730
731 Open a directory for reading.
732
733         $dir = POSIX::opendir( "/tmp" );
734         @files = POSIX::readdir( $dir );
735         POSIX::closedir( $dir );
736
737 Returns C<undef> on failure.
738
739 =item pathconf
740
741 Retrieves the value of a configurable limit on a file or directory.
742
743 The following will determine the maximum length of the longest allowable
744 pathname on the filesystem which holds C</tmp>.
745
746         $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX );
747
748 Returns C<undef> on failure.
749
750 =item pause
751
752 This is similar to the C function C<pause()>.
753
754 Returns C<undef> on failure.
755
756 =item perror
757
758 This is identical to the C function C<perror()>.
759
760 =item pipe
761
762 Create an interprocess channel.  This returns file descriptors like those
763 returned by C<POSIX::open>.
764
765         ($fd0, $fd1) = POSIX::pipe();
766         POSIX::write( $fd0, "hello", 5 );
767         POSIX::read( $fd1, $buf, 5 );
768
769 =item pow
770
771 Computes $x raised to the power $exponent.
772
773         $ret = POSIX::pow( $x, $exponent );
774
775 =item printf
776
777 Prints the specified arguments to STDOUT.
778
779 =item putc
780
781 putc() is C-specific--use print instead.
782
783 =item putchar
784
785 putchar() is C-specific--use print instead.
786
787 =item puts
788
789 puts() is C-specific--use print instead.
790
791 =item qsort
792
793 qsort() is C-specific, use sort instead.
794
795 =item raise
796
797 Sends the specified signal to the current process.
798
799 =item rand
800
801 rand() is non-portable, use Perl's rand instead.
802
803 =item read
804
805 Read from a file.  This uses file descriptors such as those obtained by
806 calling C<POSIX::open>.  If the buffer C<$buf> is not large enough for the
807 read then Perl will extend it to make room for the request.
808
809         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
810         $bytes = POSIX::read( $fd, $buf, 3 );
811
812 Returns C<undef> on failure.
813
814 =item readdir
815
816 This is identical to Perl's builtin C<readdir()> function.
817
818 =item realloc
819
820 realloc() is C-specific.
821
822 =item remove
823
824 This is identical to Perl's builtin C<unlink()> function.
825
826 =item rename
827
828 This is identical to Perl's builtin C<rename()> function.
829
830 =item rewind
831
832 Seeks to the beginning of the file.
833
834 =item rewinddir
835
836 This is identical to Perl's builtin C<rewinddir()> function.
837
838 =item rmdir
839
840 This is identical to Perl's builtin C<rmdir()> function.
841
842 =item scanf
843
844 scanf() is C-specific--use <> and regular expressions instead.
845
846 =item setgid
847
848 Sets the real group id for this process.
849
850 =item setjmp
851
852 setjmp() is C-specific: use eval {} instead.
853
854 =item setlocale
855
856 Modifies and queries program's locale.
857
858 The following will set the traditional UNIX system locale behavior
859 (the second argument C<"C">).
860
861         $loc = POSIX::setlocale( &POSIX::LC_ALL, "C" );
862
863 The following will query (the missing second argument) the current
864 LC_CTYPE category.
865
866         $loc = POSIX::setlocale( &POSIX::LC_CTYPE);
867
868 The following will set the LC_CTYPE behaviour according to the locale
869 environment variables (the second argument C<"">).
870 Please see your systems L<setlocale(3)> documentation for the locale
871 environment variables' meaning or consult L<perllocale>.
872
873         $loc = POSIX::setlocale( &POSIX::LC_CTYPE, "");
874
875 The following will set the LC_COLLATE behaviour to Argentinian
876 Spanish. B<NOTE>: The naming and availability of locales depends on
877 your operating system. Please consult L<perllocale> for how to find
878 out which locales are available in your system.
879
880         $loc = POSIX::setlocale( &POSIX::LC_ALL, "es_AR.ISO8859-1" );
881
882 =item setpgid
883
884 This is similar to the C function C<setpgid()>.
885
886 Returns C<undef> on failure.
887
888 =item setsid
889
890 This is identical to the C function C<setsid()>.
891
892 =item setuid
893
894 Sets the real user id for this process.
895
896 =item sigaction
897
898 Detailed signal management.  This uses C<POSIX::SigAction> objects for the
899 C<action> and C<oldaction> arguments.  Consult your system's C<sigaction>
900 manpage for details.
901
902 Synopsis:
903
904         sigaction(sig, action, oldaction = 0)
905
906 Returns C<undef> on failure.
907
908 =item siglongjmp
909
910 siglongjmp() is C-specific: use die instead.
911
912 =item sigpending
913
914 Examine signals that are blocked and pending.  This uses C<POSIX::SigSet>
915 objects for the C<sigset> argument.  Consult your system's C<sigpending>
916 manpage for details.
917
918 Synopsis:
919
920         sigpending(sigset)
921
922 Returns C<undef> on failure.
923
924 =item sigprocmask
925
926 Change and/or examine calling process's signal mask.  This uses
927 C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
928 Consult your system's C<sigprocmask> manpage for details.
929
930 Synopsis:
931
932         sigprocmask(how, sigset, oldsigset = 0)
933
934 Returns C<undef> on failure.
935
936 =item sigsetjmp
937
938 sigsetjmp() is C-specific: use eval {} instead.
939
940 =item sigsuspend
941
942 Install a signal mask and suspend process until signal arrives.  This uses
943 C<POSIX::SigSet> objects for the C<signal_mask> argument.  Consult your
944 system's C<sigsuspend> manpage for details.
945
946 Synopsis:
947
948         sigsuspend(signal_mask)
949
950 Returns C<undef> on failure.
951
952 =item sin
953
954 This is identical to Perl's builtin C<sin()> function.
955
956 =item sinh
957
958 This is identical to the C function C<sinh()>.
959
960 =item sleep
961
962 This is identical to Perl's builtin C<sleep()> function.
963
964 =item sprintf
965
966 This is identical to Perl's builtin C<sprintf()> function.
967
968 =item sqrt
969
970 This is identical to Perl's builtin C<sqrt()> function.
971
972 =item srand
973
974 srand().
975
976 =item sscanf
977
978 sscanf() is C-specific--use regular expressions instead.
979
980 =item stat
981
982 This is identical to Perl's builtin C<stat()> function.
983
984 =item strcat
985
986 strcat() is C-specific, use .= instead.
987
988 =item strchr
989
990 strchr() is C-specific, use index() instead.
991
992 =item strcmp
993
994 strcmp() is C-specific, use eq instead.
995
996 =item strcoll
997
998 This is identical to the C function C<strcoll()>.
999
1000 =item strcpy
1001
1002 strcpy() is C-specific, use = instead.
1003
1004 =item strcspn
1005
1006 strcspn() is C-specific, use regular expressions instead.
1007
1008 =item strerror
1009
1010 Returns the error string for the specified errno.
1011
1012 =item strftime
1013
1014 Convert date and time information to string.  Returns the string.
1015
1016 Synopsis:
1017
1018         strftime(fmt, sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0)
1019
1020 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
1021 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
1022 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
1023 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
1024 about these and the other arguments.
1025
1026 The string for Tuesday, December 12, 1995.
1027
1028         $str = POSIX::strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2 );
1029         print "$str\n";
1030
1031 =item strlen
1032
1033 strlen() is C-specific, use length instead.
1034
1035 =item strncat
1036
1037 strncat() is C-specific, use .= instead.
1038
1039 =item strncmp
1040
1041 strncmp() is C-specific, use eq instead.
1042
1043 =item strncpy
1044
1045 strncpy() is C-specific, use = instead.
1046
1047 =item stroul
1048
1049 stroul() is C-specific.
1050
1051 =item strpbrk
1052
1053 strpbrk() is C-specific.
1054
1055 =item strrchr
1056
1057 strrchr() is C-specific, use rindex() instead.
1058
1059 =item strspn
1060
1061 strspn() is C-specific.
1062
1063 =item strstr
1064
1065 This is identical to Perl's builtin C<index()> function.
1066
1067 =item strtod
1068
1069 String to double translation. Returns the parsed number and the number
1070 of characters in the unparsed portion of the string.  Truly
1071 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1072 error, so clear $! before calling strtod.  However, non-POSIX systems
1073 may not check for overflow, and therefore will never set $!.
1074
1075 strtod should respect any POSIX I<setlocale()> settings.
1076
1077 To parse a string $str as a floating point number use
1078
1079     $! = 0;
1080     ($num, $n_unparsed) = POSIX::strtod($str);
1081
1082 The second returned item and $! can be used to check for valid input:
1083
1084     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1085         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1086     }
1087
1088 When called in a scalar context strtod returns the parsed number.
1089
1090 =item strtok
1091
1092 strtok() is C-specific.
1093
1094 =item strtol
1095
1096 String to (long) integer translation.  Returns the parsed number and
1097 the number of characters in the unparsed portion of the string.  Truly
1098 POSIX-compliant systems set $! ($ERRNO) to indicate a translation
1099 error, so clear $! before calling strtol.  However, non-POSIX systems
1100 may not check for overflow, and therefore will never set $!.
1101
1102 strtol should respect any POSIX I<setlocale()> settings.
1103
1104 To parse a string $str as a number in some base $base use
1105
1106     $! = 0;
1107     ($num, $n_unparsed) = POSIX::strtol($str, $base);
1108
1109 The base should be zero or between 2 and 36, inclusive.  When the base
1110 is zero or omitted strtol will use the string itself to determine the
1111 base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1112 octal; any other leading characters mean decimal.  Thus, "1234" is
1113 parsed as a decimal number, "01234" as an octal number, and "0x1234"
1114 as a hexadecimal number.
1115
1116 The second returned item and $! can be used to check for valid input:
1117
1118     if (($str eq '') || ($n_unparsed != 0) || !$!) {
1119         die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1120     }
1121
1122 When called in a scalar context strtol returns the parsed number.
1123
1124 =item strtoul
1125
1126 String to unsigned (long) integer translation.  strtoul is identical
1127 to strtol except that strtoul only parses unsigned integers.  See
1128 I<strtol> for details.
1129
1130 Note: Some vendors supply strtod and strtol but not strtoul.
1131 Other vendors that do suply strtoul parse "-1" as a valid value.
1132
1133 =item strxfrm
1134
1135 String transformation.  Returns the transformed string.
1136
1137         $dst = POSIX::strxfrm( $src );
1138
1139 =item sysconf
1140
1141 Retrieves values of system configurable variables.
1142
1143 The following will get the machine's clock speed.
1144
1145         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1146
1147 Returns C<undef> on failure.
1148
1149 =item system
1150
1151 This is identical to Perl's builtin C<system()> function.
1152
1153 =item tan
1154
1155 This is identical to the C function C<tan()>.
1156
1157 =item tanh
1158
1159 This is identical to the C function C<tanh()>.
1160
1161 =item tcdrain
1162
1163 This is similar to the C function C<tcdrain()>.
1164
1165 Returns C<undef> on failure.
1166
1167 =item tcflow
1168
1169 This is similar to the C function C<tcflow()>.
1170
1171 Returns C<undef> on failure.
1172
1173 =item tcflush
1174
1175 This is similar to the C function C<tcflush()>.
1176
1177 Returns C<undef> on failure.
1178
1179 =item tcgetpgrp
1180
1181 This is identical to the C function C<tcgetpgrp()>.
1182
1183 =item tcsendbreak
1184
1185 This is similar to the C function C<tcsendbreak()>.
1186
1187 Returns C<undef> on failure.
1188
1189 =item tcsetpgrp
1190
1191 This is similar to the C function C<tcsetpgrp()>.
1192
1193 Returns C<undef> on failure.
1194
1195 =item time
1196
1197 This is identical to Perl's builtin C<time()> function.
1198
1199 =item times
1200
1201 The times() function returns elapsed realtime since some point in the past
1202 (such as system startup), user and system times for this process, and user
1203 and system times used by child processes.  All times are returned in clock
1204 ticks.
1205
1206     ($realtime, $user, $system, $cuser, $csystem) = POSIX::times();
1207
1208 Note: Perl's builtin C<times()> function returns four values, measured in
1209 seconds.
1210
1211 =item tmpfile
1212
1213 Use method C<IO::File::new_tmpfile()> instead.
1214
1215 =item tmpnam
1216
1217 Returns a name for a temporary file.
1218
1219         $tmpfile = POSIX::tmpnam();
1220
1221 =item tolower
1222
1223 This is identical to Perl's builtin C<lc()> function.
1224
1225 =item toupper
1226
1227 This is identical to Perl's builtin C<uc()> function.
1228
1229 =item ttyname
1230
1231 This is identical to the C function C<ttyname()>.
1232
1233 =item tzname
1234
1235 Retrieves the time conversion information from the C<tzname> variable.
1236
1237         POSIX::tzset();
1238         ($std, $dst) = POSIX::tzname();
1239
1240 =item tzset
1241
1242 This is identical to the C function C<tzset()>.
1243
1244 =item umask
1245
1246 This is identical to Perl's builtin C<umask()> function.
1247
1248 =item uname
1249
1250 Get name of current operating system.
1251
1252         ($sysname, $nodename, $release, $version, $machine ) = POSIX::uname();
1253
1254 =item ungetc
1255
1256 Use method C<IO::Handle::ungetc()> instead.
1257
1258 =item unlink
1259
1260 This is identical to Perl's builtin C<unlink()> function.
1261
1262 =item utime
1263
1264 This is identical to Perl's builtin C<utime()> function.
1265
1266 =item vfprintf
1267
1268 vfprintf() is C-specific.
1269
1270 =item vprintf
1271
1272 vprintf() is C-specific.
1273
1274 =item vsprintf
1275
1276 vsprintf() is C-specific.
1277
1278 =item wait
1279
1280 This is identical to Perl's builtin C<wait()> function.
1281
1282 =item waitpid
1283
1284 Wait for a child process to change state.  This is identical to Perl's
1285 builtin C<waitpid()> function.
1286
1287         $pid = POSIX::waitpid( -1, &POSIX::WNOHANG );
1288         print "status = ", ($? / 256), "\n";
1289
1290 =item wcstombs
1291
1292 This is identical to the C function C<wcstombs()>.
1293
1294 =item wctomb
1295
1296 This is identical to the C function C<wctomb()>.
1297
1298 =item write
1299
1300 Write to a file.  This uses file descriptors such as those obtained by
1301 calling C<POSIX::open>.
1302
1303         $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
1304         $buf = "hello";
1305         $bytes = POSIX::write( $b, $buf, 5 );
1306
1307 Returns C<undef> on failure.
1308
1309 =back
1310
1311 =head1 CLASSES
1312
1313 =head2 POSIX::SigAction
1314
1315 =over 8
1316
1317 =item new
1318
1319 Creates a new C<POSIX::SigAction> object which corresponds to the C
1320 C<struct sigaction>.  This object will be destroyed automatically when it is
1321 no longer needed.  The first parameter is the fully-qualified name of a sub
1322 which is a signal-handler.  The second parameter is a C<POSIX::SigSet>
1323 object, it defaults to the empty set.  The third parameter contains the
1324 C<sa_flags>, it defaults to 0.
1325
1326         $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
1327         $sigaction = POSIX::SigAction->new( 'main::handler', $sigset, &POSIX::SA_NOCLDSTOP );
1328
1329 This C<POSIX::SigAction> object should be used with the C<POSIX::sigaction()>
1330 function.
1331
1332 =back
1333
1334 =head2 POSIX::SigSet
1335
1336 =over 8
1337
1338 =item new
1339
1340 Create a new SigSet object.  This object will be destroyed automatically
1341 when it is no longer needed.  Arguments may be supplied to initialize the
1342 set.
1343
1344 Create an empty set.
1345
1346         $sigset = POSIX::SigSet->new;
1347
1348 Create a set with SIGUSR1.
1349
1350         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
1351
1352 =item addset
1353
1354 Add a signal to a SigSet object.
1355
1356         $sigset->addset( &POSIX::SIGUSR2 );
1357
1358 Returns C<undef> on failure.
1359
1360 =item delset
1361
1362 Remove a signal from the SigSet object.
1363
1364         $sigset->delset( &POSIX::SIGUSR2 );
1365
1366 Returns C<undef> on failure.
1367
1368 =item emptyset
1369
1370 Initialize the SigSet object to be empty.
1371
1372         $sigset->emptyset();
1373
1374 Returns C<undef> on failure.
1375
1376 =item fillset
1377
1378 Initialize the SigSet object to include all signals.
1379
1380         $sigset->fillset();
1381
1382 Returns C<undef> on failure.
1383
1384 =item ismember
1385
1386 Tests the SigSet object to see if it contains a specific signal.
1387
1388         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
1389                 print "contains SIGUSR1\n";
1390         }
1391
1392 =back
1393
1394 =head2 POSIX::Termios
1395
1396 =over 8
1397
1398 =item new
1399
1400 Create a new Termios object.  This object will be destroyed automatically
1401 when it is no longer needed.  A Termios object corresponds to the termios
1402 C struct.  new() mallocs a new one, getattr() fills it from a file descriptor,
1403 and setattr() sets a file descriptor's parameters to match Termios' contents.
1404
1405         $termios = POSIX::Termios->new;
1406
1407 =item getattr
1408
1409 Get terminal control attributes.
1410
1411 Obtain the attributes for stdin.
1412
1413         $termios->getattr()
1414
1415 Obtain the attributes for stdout.
1416
1417         $termios->getattr( 1 )
1418
1419 Returns C<undef> on failure.
1420
1421 =item getcc
1422
1423 Retrieve a value from the c_cc field of a termios object.  The c_cc field is
1424 an array so an index must be specified.
1425
1426         $c_cc[1] = $termios->getcc(1);
1427
1428 =item getcflag
1429
1430 Retrieve the c_cflag field of a termios object.
1431
1432         $c_cflag = $termios->getcflag;
1433
1434 =item getiflag
1435
1436 Retrieve the c_iflag field of a termios object.
1437
1438         $c_iflag = $termios->getiflag;
1439
1440 =item getispeed
1441
1442 Retrieve the input baud rate.
1443
1444         $ispeed = $termios->getispeed;
1445
1446 =item getlflag
1447
1448 Retrieve the c_lflag field of a termios object.
1449
1450         $c_lflag = $termios->getlflag;
1451
1452 =item getoflag
1453
1454 Retrieve the c_oflag field of a termios object.
1455
1456         $c_oflag = $termios->getoflag;
1457
1458 =item getospeed
1459
1460 Retrieve the output baud rate.
1461
1462         $ospeed = $termios->getospeed;
1463
1464 =item setattr
1465
1466 Set terminal control attributes.
1467
1468 Set attributes immediately for stdout.
1469
1470         $termios->setattr( 1, &POSIX::TCSANOW );
1471
1472 Returns C<undef> on failure.
1473
1474 =item setcc
1475
1476 Set a value in the c_cc field of a termios object.  The c_cc field is an
1477 array so an index must be specified.
1478
1479         $termios->setcc( &POSIX::VEOF, 1 );
1480
1481 =item setcflag
1482
1483 Set the c_cflag field of a termios object.
1484
1485         $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
1486
1487 =item setiflag
1488
1489 Set the c_iflag field of a termios object.
1490
1491         $termios->setiflag( $c_iflag | &POSIX::BRKINT );
1492
1493 =item setispeed
1494
1495 Set the input baud rate.
1496
1497         $termios->setispeed( &POSIX::B9600 );
1498
1499 Returns C<undef> on failure.
1500
1501 =item setlflag
1502
1503 Set the c_lflag field of a termios object.
1504
1505         $termios->setlflag( $c_lflag | &POSIX::ECHO );
1506
1507 =item setoflag
1508
1509 Set the c_oflag field of a termios object.
1510
1511         $termios->setoflag( $c_oflag | &POSIX::OPOST );
1512
1513 =item setospeed
1514
1515 Set the output baud rate.
1516
1517         $termios->setospeed( &POSIX::B9600 );
1518
1519 Returns C<undef> on failure.
1520
1521 =item Baud rate values
1522
1523 B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110
1524
1525 =item Terminal interface values
1526
1527 TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF
1528
1529 =item c_cc field values
1530
1531 VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS
1532
1533 =item c_cflag field values
1534
1535 CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD
1536
1537 =item c_iflag field values
1538
1539 BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK
1540
1541 =item c_lflag field values
1542
1543 ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP
1544
1545 =item c_oflag field values
1546
1547 OPOST
1548
1549 =back
1550
1551 =head1 PATHNAME CONSTANTS
1552
1553 =over 8
1554
1555 =item Constants
1556
1557 _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
1558
1559 =back
1560
1561 =head1 POSIX CONSTANTS
1562
1563 =over 8
1564
1565 =item Constants
1566
1567 _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
1568
1569 =back
1570
1571 =head1 SYSTEM CONFIGURATION
1572
1573 =over 8
1574
1575 =item Constants
1576
1577 _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
1578
1579 =back
1580
1581 =head1 ERRNO
1582
1583 =over 8
1584
1585 =item Constants
1586
1587 E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF
1588 EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ
1589 EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR
1590 EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG
1591 ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC
1592 ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR
1593 ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE
1594 EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS
1595 ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS
1596 ETXTBSY EUSERS EWOULDBLOCK EXDEV
1597
1598 =back
1599
1600 =head1 FCNTL
1601
1602 =over 8
1603
1604 =item Constants
1605
1606 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
1607
1608 =back
1609
1610 =head1 FLOAT
1611
1612 =over 8
1613
1614 =item Constants
1615
1616 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
1617
1618 =back
1619
1620 =head1 LIMITS
1621
1622 =over 8
1623
1624 =item Constants
1625
1626 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
1627
1628 =back
1629
1630 =head1 LOCALE
1631
1632 =over 8
1633
1634 =item Constants
1635
1636 LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
1637
1638 =back
1639
1640 =head1 MATH
1641
1642 =over 8
1643
1644 =item Constants
1645
1646 HUGE_VAL
1647
1648 =back
1649
1650 =head1 SIGNAL
1651
1652 =over 8
1653
1654 =item Constants
1655
1656 SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART
1657 SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT
1658 SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU
1659 SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK
1660 SIG_UNBLOCK
1661
1662 =back
1663
1664 =head1 STAT
1665
1666 =over 8
1667
1668 =item Constants
1669
1670 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
1671
1672 =item Macros
1673
1674 S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG
1675
1676 =back
1677
1678 =head1 STDLIB
1679
1680 =over 8
1681
1682 =item Constants
1683
1684 EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX
1685
1686 =back
1687
1688 =head1 STDIO
1689
1690 =over 8
1691
1692 =item Constants
1693
1694 BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX
1695
1696 =back
1697
1698 =head1 TIME
1699
1700 =over 8
1701
1702 =item Constants
1703
1704 CLK_TCK CLOCKS_PER_SEC
1705
1706 =back
1707
1708 =head1 UNISTD
1709
1710 =over 8
1711
1712 =item Constants
1713
1714 R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STRERR_FILENO W_OK X_OK
1715
1716 =back
1717
1718 =head1 WAIT
1719
1720 =over 8
1721
1722 =item Constants
1723
1724 WNOHANG WUNTRACED
1725
1726 =item Macros
1727
1728 WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
1729
1730 =back
1731
1732 =head1 CREATION
1733
1734 This document generated by ./mkposixman.PL version 19960129.
1735