perl 5.003_03: x2p/str.c
[perl.git] / ext / POSIX / mkposixman.pl
1 #!/tmp/perl5 -w
2 #!/tmp/perl5
3
4 # Ramrodded by Dean Roehrich.
5 #
6 # Submissions for function descriptions are needed.  Don't write a tutorial,
7 # and don't repeat things that can be found in the system's manpages,
8 # just give a quick 2-3 line note and a one-line example.
9 #
10 # Check the latest version of the Perl5 Module List for Dean's current
11 # email address (listed as DMR).
12 #
13 my $VERS = 951129;  # yymmdd
14
15 local *main::XS;
16 local *main::PM;
17
18 open( XS, "<POSIX.xs" ) || die "Unable to open POSIX.xs";
19 open( PM, "<POSIX.pm" ) || die "Unable to open POSIX.pm";
20 close STDOUT;
21 open( STDOUT, ">POSIX.pod" ) || die "Unable to open POSIX.pod";
22
23 print <<'EOQ';
24 =head1 NAME
25
26 POSIX - Perl interface to IEEE Std 1003.1
27
28 =head1 SYNOPSIS
29
30     use POSIX;
31     use POSIX qw(setsid);
32     use POSIX qw(:errno_h :fcntl_h);
33
34     printf "EINTR is %d\n", EINTR;
35
36     $sess_id = POSIX::setsid();
37
38     $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
39         # note: that's a filedescriptor, *NOT* a filehandle
40
41 =head1 DESCRIPTION
42
43 The POSIX module permits you to access all (or nearly all) the standard
44 POSIX 1003.1 identifiers.  Many of these identifiers have been given Perl-ish
45 interfaces.  Things which are C<#defines> in C, like EINTR or O_NDELAY, are
46 automatically exported into your namespace.  All functions are only exported
47 if you ask for them explicitly.  Most likely people will prefer to use the
48 fully-qualified function names.
49
50 This document gives a condensed list of the features available in the POSIX
51 module.  Consult your operating system's manpages for general information on
52 most features.  Consult L<perlfunc> for functions which are noted as being
53 identical to Perl's builtin functions.
54
55 The first section describes POSIX functions from the 1003.1 specification.
56 The second section describes some classes for signal objects, TTY objects,
57 and other miscellaneous objects.  The remaining sections list various
58 constants and macros in an organization which roughly follows IEEE Std
59 1003.1b-1993.
60
61 =head1 NOTE
62
63 The POSIX module is probably the most complex Perl module supplied with
64 the standard distribution.  It incorporates autoloading, namespace games,
65 and dynamic loading of code that's in Perl, C, or both.  It's a great
66 source of wisdom.
67
68 =head1 CAVEATS 
69
70 A few functions are not implemented because they are C specific.  If you
71 attempt to call these, they will print a message telling you that they
72 aren't implemented, and suggest using the Perl equivalent should one
73 exist.  For example, trying to access the setjmp() call will elicit the
74 message "setjmp() is C-specific: use eval {} instead".
75
76 Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
77 are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
78 For example, one vendor may not define EDEADLK, or the semantics of the
79 errno values set by open(2) might not be quite right.  Perl does not
80 attempt to verify POSIX compliance.  That means you can currently
81 successfully say "use POSIX",  and then later in your program you find
82 that your vendor has been lax and there's no usable ICANON macro after
83 all.  This could be construed to be a bug.
84
85 EOQ
86
87 use strict;
88
89
90 my $constants = {};
91 my $macros = {};
92 my $packages = [];
93 my $posixpack = Package->new( 'POSIX' );
94 my $descriptions = Description->new;
95
96 get_constants( 'XS', $constants, $macros );
97 get_functions( 'XS', $packages, $posixpack );
98 get_PMfunctions( 'PM', $packages, $posixpack, $descriptions );
99
100
101 # It is possible that the matches of setup_*() may depend on
102 # the matches of an earlier setup_*().  If you change the order,
103 # be careful that you're getting only what you want, and no more.
104 #
105 my $termios_flags = setup_termios( $constants );
106 my $wait_stuff = setup_wait( $constants, $macros );
107 my $stat = setup_file_char( $constants, $macros );
108 my $port = setup_pat( $constants, '^_POSIX' );
109 my $sc = setup_pat( $constants, '^_SC_' );
110 my $pc = setup_pat( $constants, '^_PC_' );
111 my $fcntl = setup_pat( $constants, '^([FO]_|FD_)' );
112 my $sigs = setup_pat( $constants, '^(SIG|SA_)' );
113 my $float = setup_pat( $constants, '^(L?DBL_|FLT_)' );
114 my $locale = setup_pat( $constants, '^LC_' );
115 my $stdio = setup_pat( $constants, '(^BUFSIZ$)|(^L_)|(^_IO...$)|(^EOF$)|(^FILENAME_MAX$)|(^TMP_MAX$)' );
116 my $stdlib = setup_pat( $constants, '(^EXIT_)|(^MB_CUR_MAX$)|(^RAND_MAX$)' );
117 my $limits = setup_pat( $constants, '(_MAX$)|(_MIN$)|(_BIT$)|(^MAX_)|(_BUF$)' );
118 my $math = setup_pat( $constants, '^HUGE_VAL$' );
119 my $time = setup_pat( $constants, '^CL' );
120 my $unistd = setup_pat( $constants, '(_FILENO$)|(^SEEK_...$)|(^._OK$)' );
121 my $errno = setup_pat( $constants, '^E' );
122
123 print_posix( $posixpack, $descriptions );
124 print_classes( $packages, $constants, $termios_flags, $descriptions );
125 print_misc( 'Pathname Constants', $pc );
126 print_misc( 'POSIX Constants', $port );
127 print_misc( 'System Configuration', $sc );
128 print_misc( 'Errno', $errno );
129 print_misc( 'Fcntl', $fcntl );
130 print_misc( 'Float', $float );
131 print_misc( 'Limits', $limits );
132 print_misc( 'Locale', $locale );
133 print_misc( 'Math', $math );
134 print_misc( 'Signal', $sigs );
135 print_misc( 'Stat', $stat );
136 print_misc( 'Stdlib', $stdlib );
137 print_misc( 'Stdio', $stdio );
138 print_misc( 'Time', $time );
139 print_misc( 'Unistd', $unistd );
140 print_misc( 'Wait', $wait_stuff );
141
142 print_vers( $VERS );
143
144 dregs( $macros, $constants );
145
146 exit(0);
147
148 Unimplemented.
149
150 sub dregs {
151         my $macros = shift;
152         my $constants = shift;
153
154         foreach (keys %$macros){
155                 warn "Unknown macro $_ in the POSIX.xs module.\n";
156         }
157         foreach (keys %$constants){
158                 warn "Unknown constant $_ in the POSIX.xs module.\n";
159         }
160 }
161
162 sub get_constants {
163         no strict 'refs';
164         my $fh = shift;
165         my $constants = shift;
166         my $macros = shift;
167         my $v;
168
169         while(<$fh>){
170                 last if /^constant/;
171         }
172         while(<$fh>){ # }{{
173                 last if /^}/;
174                 if( /return\s+([^;]+)/ ){
175                         $v = $1;
176                         # skip non-symbols
177                         if( $v !~ /^\d+$/ ){
178                                 # remove any C casts
179                                 $v =~ s,\(.*?\)\s*(\w),$1,;
180                                 # is it a macro?
181                                 if( $v =~ s/(\(.*?\))// ){
182                                         $macros->{$v} = $1;
183                                 }
184                                 else{
185                                         $constants->{$v} = 1;
186                                 }
187                         }
188                 }
189         }
190 }
191
192 Close the file.  This uses file descriptors such as those obtained by calling
193 C<POSIX::open>.
194
195         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
196         POSIX::close( $fd );
197
198 sub get_functions {
199         no strict 'refs';
200         my $fh = shift;
201         my $packages = shift;
202         my $posixpack = shift;
203         my $header = 0;
204         my $pack = '';
205         my $prefix = '';
206         my( $x, $y );
207         my( $curfuncs, $curpack );
208         my $ret;
209
210         while(<$fh>){
211                 if( /^MODULE.*?PACKAGE\s*=\s*([^\s]+)/ ){
212                         $pack = $1;
213                         $prefix = '';
214                         if( /PREFIX\s*=\s*([^\n]+)/ ){
215                                 $prefix = $1;
216                         }
217                         #print "package($pack) prefix($prefix)\n";
218                         if( $pack eq 'POSIX' ){
219                                 $curpack = $posixpack;
220                         }
221                         else{
222                                 $curpack = Package->new( $pack );
223                                 push @$packages, $curpack;
224                         }
225                         $curfuncs = $curpack->curfuncs;
226                         next;
227                 }
228
229                 chop;
230                 # find function header
231                 if( /^[^\s]/ && ! /^#/ ){
232                         $ret = /^SysRet/ ? 2 : 1;
233                         chop($x = <$fh>);
234                         next if( $pack eq 'POSIX' and $x =~ /^constant/ );
235                         $x =~ /^(.*?)\s*\((.*?)\)/;
236                         ($x,$y) = ($1, $2); # func,sig
237                         $x =~ s/^$prefix//;
238                         $curfuncs->{$x} = $ret;
239                         ++$header
240                 }
241                 # leave function header
242                 else{
243                         $header = 0;
244                 }
245         }
246 }
247
248
249 sub get_PMfunctions {
250         no strict 'refs';
251         my $fh = shift;
252         my $packages = shift;
253         my $posixpack = shift;
254         my $desc = shift;
255         my $pack = '';
256         my( $curfuncs, $curpack );
257         my $y;
258         my $x;
259         my $sub = '';
260
261         # find the second package statement.
262         while(<$fh>){
263                 if( /^package\s+(.*?);/ ){
264                         $pack = $1;
265                         last if $pack ne 'POSIX';
266                 }
267         }
268
269         # Check if this package is already
270         # being used.
271         $curpack = '';
272         foreach (@$packages){
273                 if( $_->name eq $pack ){
274                         $curpack = $_;
275                         last;
276                 }
277         }
278         # maybe start a new package.
279         if( $curpack eq '' ){
280                 $curpack = Package->new( $pack );
281                 push @$packages, $curpack;
282         }
283         $curfuncs = $curpack->curfuncs;
284
285         # now fetch functions
286         while(<$fh>){
287                 if( /^package\s+(.*?);/ ){
288                         $pack = $1;
289                         if( $pack eq 'POSIX' ){
290                                 $curpack = $posixpack;
291                         }
292                         else{
293                                 # Check if this package is already
294                                 # being used.
295                                 $curpack = '';
296                                 foreach (@$packages){
297                                         if( $_->name() eq $pack ){
298                                                 $curpack = $_;
299                                                 last;
300                                         }
301                                 }
302                                 # maybe start a new package.
303                                 if( $curpack eq '' ){
304                                         $curpack = Package->new( $pack );
305                                         push @$packages, $curpack;
306                                 }
307                         }
308                         $curfuncs = $curpack->curfuncs;
309                         next;
310                 }
311                 if( /^sub\s+(.*?)\s/ ){
312                         $sub = $1;
313
314                         # special cases
315                         if( $pack eq 'POSIX::SigAction' and
316                            $sub eq 'new' ){
317                                 $curfuncs->{$sub} = 1;
318                         }
319                         elsif( $pack eq 'POSIX' and $sub eq 'perror' ){
320                                 $curfuncs->{$sub} = 1;
321                         }
322
323                         next;
324                 }
325                 if( /usage.*?\((.*?)\)/ ){
326                         $y = $1;
327                         $curfuncs->{$sub} = 1;
328                         next;
329                  }
330                  if( /^\s+unimpl\s+"(.*?)"/ ){
331                         $y = $1;
332                         $y =~ s/, stopped//;
333                         $desc->append( $pack, $sub, $y );
334                         $curfuncs->{$sub} = 1;
335                         next;
336                  }
337                  if( /^\s+redef\s+"(.*?)"/ ){
338                         $x = $1;
339                         $y = "Use method C<$x> instead";
340                         $desc->append( $pack, $sub, $y );
341                         $curfuncs->{$sub} = 1;
342                         next;
343                  }
344         }
345 }
346
347 Retrieves the value of a configurable limit on a file or directory.  This
348 uses file descriptors such as those obtained by calling C<POSIX::open>.
349
350 The following will determine the maximum length of the longest allowable
351 pathname on the filesystem which holds C</tmp/foo>.
352
353         $fd = POSIX::open( "/tmp/foo", &POSIX::O_RDONLY );
354         $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX );
355 Return the mantissa and exponent of a floating-point number.
356
357         ($mantissa, $exponent) = POSIX::frexp( 3.14 );
358 Get file status.  This uses file descriptors such as those obtained by
359 calling C<POSIX::open>.  The data returned is identical to the data from
360 Perl's builtin C<stat> function.
361
362         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
363         @stats = POSIX::fstat( $fd );
364
365 sub print_posix {
366         my $pack = shift;
367         my $desc = shift;
368
369         print "=head1 FUNCTIONS\n\n";
370         print "=over 8\n\n";
371         dumpfuncs( $pack, $desc );
372         print "=back\n\n";
373 }
374
375 sub print_classes {
376         my $packages = shift;
377         my $constants = shift;
378         my $termios = shift;
379         my $desc = shift;
380         my $pack;
381         my @pkgs;
382
383         print "=head1 CLASSES\n\n";
384         @pkgs = sort { $main::a->name() cmp $main::b->name() } @$packages;
385         while( @pkgs ){
386                 $pack = shift @pkgs;
387                 print "=head2 ", $pack->name(), "\n\n";
388                 print "=over 8\n\n";
389
390                 dumpfuncs( $pack, $desc );
391
392                 if( $pack->name() =~ /termios/i ){
393                         dumpflags( $termios );
394                 }
395                 print "=back\n\n";
396         }
397 }
398
399 sub setup_termios {
400         my $constants = shift;
401         my $obj;
402
403         $obj = {
404                 'c_iflag field' => [qw( BRKINT ICRNL IGNBRK IGNCR IGNPAR
405                                         INLCR INPCK ISTRIP IXOFF IXON
406                                         PARMRK )],
407                 'c_oflag field' => [qw( OPOST )],
408                 'c_cflag field' => [qw( CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8
409                                         CSTOPB HUPCL PARENB PARODD )],
410                 'c_lflag field' => [qw( ECHO ECHOE ECHOK ECHONL ICANON
411                                         IEXTEN ISIG NOFLSH TOSTOP )],
412                 'c_cc field'    => [qw( VEOF VEOL VERASE VINTR VKILL VQUIT
413                                         VSUSP VSTART VSTOP VMIN VTIME NCCS )],
414                 'Baud rate'     => [],
415                 'Terminal interface' => [],
416         };
417         # look for baud rates in constants, add to termios
418         foreach (keys %$constants){
419                 if( /^B\d+$/ ){
420                         push @{$obj->{'Baud rate'}}, $_;
421                 }
422         }
423         # look for TC* in constants, add to termios
424         foreach (keys %$constants){
425                 if( /^TC/ ){
426                         push @{$obj->{'Terminal interface'}}, $_;
427                 }
428         }
429         # trim the constants
430         foreach (keys %$obj){
431                 trim_hash( 'Constant', $obj->{$_}, $constants );
432         }
433         return $obj;
434 }
435
436
437 sub dumpfuncs {
438         my $pack = shift;
439         my $desc = shift;
440         my $curfuncs = $pack->curfuncs;
441         my $pname = $pack->name;
442         my $func;
443         my @funcs = sort keys %$curfuncs;
444
445         if( exists $curfuncs->{'new'} ){ # do new first
446                 @funcs = grep( $_ ne 'new', @funcs );
447                 unshift @funcs, 'new';
448         }
449         while( @funcs ){
450                 $func = shift @funcs;
451                 if( $func eq 'DESTROY' ){
452                         next;    # don't do DESTROY
453                 }
454                 print "=item $func\n\n";
455                 if( $desc->print( $pname, $func, $curfuncs->{$func} ) ){
456                         # if it was printed, note that
457                         delete $curfuncs->{$func};
458                 }
459         }
460 }
461
462 sub dumpflags {
463         my $flags = shift;
464         my $field;
465
466         foreach $field (sort keys %$flags){
467                 print "=item $field values\n\n";
468                 print join( ' ', @{$flags->{$field}} ), "\n\n";
469         }
470 }
471
472 sub setup_wait {
473         my $constants = shift;
474         my $macros = shift;
475         my $obj;
476
477         $obj = {
478                 'Macros'    => [qw( WIFEXITED WEXITSTATUS WIFSIGNALED
479                                     WTERMSIG WIFSTOPPED WSTOPSIG )],
480                 'Constants' => [qw( WNOHANG WUNTRACED )],
481         };
482         trim_hash( 'Constant', $obj->{Constants}, $constants );
483         trim_hash( 'Macro', $obj->{Macros}, $macros );
484         return $obj;
485 }
486
487 sub setup_file_char {
488         my $constants = shift;
489         my $macros = shift;
490         my $obj;
491
492         $obj = {
493                 'Macros'    => [],
494                 'Constants' => [],
495         };
496         # find S_* constants and add to object.
497         foreach (sort keys %$constants){
498                 if( /^S_/ ){
499                         push @{$obj->{'Constants'}}, $_;
500                 }
501         }
502         # find S_* macros and add to object.
503         foreach (sort keys %$macros){
504                 if( /^S_/ ){
505                         push @{$obj->{'Macros'}}, $_;
506                 }
507         }
508         # trim the hashes
509         trim_hash( 'Constant', $obj->{Constants}, $constants );
510         trim_hash( 'Macro', $obj->{Macros}, $macros );
511         return $obj;
512 }
513
514
515 sub setup_pat {
516         my $constants = shift;
517         my $pat = shift;
518         my $obj;
519
520         $obj = { 'Constants' => [] };
521         foreach (sort keys %$constants){
522                 if( /$pat/ ){
523                         push @{$obj->{'Constants'}}, $_;
524                 }
525         }
526         trim_hash( 'Constant', $obj->{Constants}, $constants );
527         return $obj;
528 }
529
530 Get numeric formatting information.  Returns a reference to a hash
531 containing the current locale formatting values.
532
533 The database for the B<de> (Deutsch or German) locale.
534
535         $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
536         print "Locale = $loc\n";
537         $lconv = POSIX::localeconv();
538         print "decimal_point    = ", $lconv->{decimal_point},   "\n";
539         print "thousands_sep    = ", $lconv->{thousands_sep},   "\n";
540         print "grouping = ", $lconv->{grouping},        "\n";
541         print "int_curr_symbol  = ", $lconv->{int_curr_symbol}, "\n";
542         print "currency_symbol  = ", $lconv->{currency_symbol}, "\n";
543         print "mon_decimal_point = ", $lconv->{mon_decimal_point}, "\n";
544         print "mon_thousands_sep = ", $lconv->{mon_thousands_sep}, "\n";
545         print "mon_grouping     = ", $lconv->{mon_grouping},    "\n";
546         print "positive_sign    = ", $lconv->{positive_sign},   "\n";
547         print "negative_sign    = ", $lconv->{negative_sign},   "\n";
548         print "int_frac_digits  = ", $lconv->{int_frac_digits}, "\n";
549         print "frac_digits      = ", $lconv->{frac_digits},     "\n";
550         print "p_cs_precedes    = ", $lconv->{p_cs_precedes},   "\n";
551         print "p_sep_by_space   = ", $lconv->{p_sep_by_space},  "\n";
552         print "n_cs_precedes    = ", $lconv->{n_cs_precedes},   "\n";
553         print "n_sep_by_space   = ", $lconv->{n_sep_by_space},  "\n";
554         print "p_sign_posn      = ", $lconv->{p_sign_posn},     "\n";
555         print "n_sign_posn      = ", $lconv->{n_sign_posn},     "\n";
556 Move the read/write file pointer.  This uses file descriptors such as
557 those obtained by calling C<POSIX::open>.
558
559         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
560         $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
561
562 sub print_vers {
563         my $vers = shift;
564
565         print "=head1 CREATION\n\n";
566         print "This document generated by $0 version $vers.\n\n";
567 }
568
569 sub print_misc {
570         my $hdr = shift;
571         my $obj = shift;
572         my $item;
573
574         print "=head1 ", uc($hdr), "\n\n";
575         print "=over 8\n\n";
576         foreach $item (sort keys %$obj){
577                 print "=item $item\n\n";
578                 print join( ' ', @{$obj->{$item}}), "\n\n";
579         }
580         print "=back\n\n";
581 }
582
583 sub trim_hash {
584         my $name = shift;
585         my $av = shift;
586         my $hv = shift;
587
588         foreach (@$av){
589                 if( exists $hv->{$_} ){
590                         delete $hv->{$_};
591                 }
592                 else{
593                         warn "$name $_ is not in the POSIX.xs module";
594                 }
595         }
596 }
597
598 { package Package; ## Package package
599
600   sub new {
601         my $type = shift;
602         my $pack = shift || die;
603         my $self = [ $pack, {} ];
604         bless $self, $type;
605   }
606   sub name {
607         my $self = shift;
608         $self->[0];
609   }
610   sub curfuncs {
611         my $self = shift;
612         $self->[1];
613   }
614   sub DESTROY {
615         my $self = shift;
616         my $pack = $self->name;
617         foreach (keys %{$self->curfuncs}){
618                 if( $_ eq 'DESTROY' ){
619                         next; # don't expect much on DESTROY
620                 }
621                 warn "Function ". $pack . "::$_ did not have a description.\n";
622         }
623   }
624 }
625 { package Description;  ## Function description
626
627   sub new {
628         my $type = shift;
629         my $self = {};
630         bless $self, $type;
631         $self->fetch;
632         return $self;
633   }
634   sub fetch {
635         my $self = shift;
636         my $pack = '';
637         my $c;
638         my( $sub, $as );
639
640         while(<main::DATA>){
641                 next if /^#/;
642                 $sub = $as = '';
643                 if( /^==(.*)/ ){
644                         $pack = $1;
645                         next;
646                 }
647                 if( /^=([^\+]+)\+\+/ ){
648                         $sub = $1;
649                         $as = $sub;
650                 }
651                 elsif( /^=([^\+]+)\+C/ ){
652                         $sub = $1;
653                         $as = 'C';
654                 }
655                 elsif( /^=([^\+]+)\+(\w+)/ ){
656                         $sub = $1;
657                         $as = $2;
658                 }
659                 elsif( /^=(.*)/ ){
660                         $sub = $1;
661                 }
662
663                 if( $sub ne '' ){
664                         $sub = $1;
665                         $self->{$pack."::$sub"} = '';
666                         $c = \($self->{$pack."::$sub"});
667                         if( $as eq 'C' ){
668                                 $$c .= "This is identical to the C function C<$sub()>.\n";
669                         }
670                         elsif( $as ne '' ){
671                                 $$c .= "This is identical to Perl's builtin C<$as()> function.\n";
672                         }
673                         next;
674                 }
675                 $$c .= $_;
676         }
677   }
678   sub DESTROY {
679         my $self = shift;
680         foreach (keys %$self){
681                 warn "Function $_ is not in the POSIX.xs module.\n";
682         }
683   }
684   sub append {
685         my $self = shift;
686         my $pack = shift;
687         my $sub = shift;
688         my $str = shift || die;
689
690         if( exists $self->{$pack."::$sub"} ){
691                 $self->{$pack."::$sub"} .= "\n$str.\n";
692         }
693         else{
694                 $self->{$pack."::$sub"} = "$str.\n";
695         }
696   }
697   sub print {
698         my $self = shift;
699         my $pack = shift;
700         my $sub = shift;
701         my $rtype = shift || die;
702         my $ret = 0;
703
704         if( exists $self->{$pack."::$sub"} ){
705                 if( $rtype > 1 ){
706                         $self->{$pack."::$sub"} =~ s/identical/similar/;
707                 }
708                 print $self->{$pack."::$sub"}, "\n";
709                 delete $self->{$pack."::$sub"};
710                 if( $rtype > 1 ){
711                         print "Returns C<undef> on failure.\n\n";
712                 }
713                 $ret = 1;
714         }
715         $ret;
716   }
717 }
718
719 Create an interprocess channel.  This returns file descriptors like those
720 returned by C<POSIX::open>.
721
722         ($fd0, $fd1) = POSIX::pipe();
723         POSIX::write( $fd0, "hello", 5 );
724         POSIX::read( $fd1, $buf, 5 );
725 Read from a file.  This uses file descriptors such as those obtained by
726 calling C<POSIX::open>.  If the buffer C<$buf> is not large enough for the
727 read then Perl will extend it to make room for the request.
728
729         $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
730         $bytes = POSIX::read( $fd, $buf, 3 );
731 This is similar to the C function C<setpgid()>.
732 Detailed signal management.  This uses C<POSIX::SigAction> objects for the
733 C<action> and C<oldaction> arguments.  Consult your system's C<sigaction>
734 manpage for details.
735
736 Synopsis:
737
738         sigaction(sig, action, oldaction = 0)
739 Install a signal mask and suspend process until signal arrives.  This uses
740 C<POSIX::SigSet> objects for the C<signal_mask> argument.  Consult your
741 system's C<sigsuspend> manpage for details.
742
743 Synopsis:
744
745         sigsuspend(signal_mask)
746 This is identical to Perl's builtin C<sprintf()> function.
747 Convert date and time information to string.  Returns the string.
748
749 Synopsis:
750
751         strftime(fmt, sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0)
752
753 The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero.
754 I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
755 year (C<year>) is given in years since 1900.  I.e. The year 1995 is 95; the
756 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
757 about these and the other arguments.
758
759 The string for Tuesday, December 12, 1995.
760
761         $str = POSIX::strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2 );
762         print "$str\n";
763 String transformation.  Returns the transformed string.
764
765         $dst = POSIX::strxfrm( $src );
766 Get name of current operating system.
767
768         ($sysname, $nodename, $release, $version, $machine ) = POSIX::uname();
769 Returns the current file position, in bytes.
770
771         $pos = $fh->tell;
772 Get terminal control attributes.
773
774 Obtain the attributes for stdin.
775
776         $termios->getattr()
777
778 Obtain the attributes for stdout.
779
780         $termios->getattr( 1 )
781 Set terminal control attributes.
782
783 Set attributes immediately for stdout.
784
785         $termios->setattr( 1, &POSIX::TCSANOW );
786
787 __END__
788 ##########
789 ==POSIX::SigSet
790 =new
791 Create a new SigSet object.  This object will be destroyed automatically
792 when it is no longer needed.  Arguments may be supplied to initialize the
793 set.
794
795 Create an empty set.
796
797         $sigset = POSIX::SigSet->new;
798
799 Create a set with SIGUSR1.
800
801         $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
802 =addset
803 Add a signal to a SigSet object.
804
805         $sigset->addset( &POSIX::SIGUSR2 );
806 =delset
807 Remove a signal from the SigSet object.
808
809         $sigset->delset( &POSIX::SIGUSR2 );
810 =emptyset
811 Initialize the SigSet object to be empty.
812
813         $sigset->emptyset();
814 =fillset
815 Initialize the SigSet object to include all signals.
816
817         $sigset->fillset();
818 =ismember
819 Tests the SigSet object to see if it contains a specific signal.
820
821         if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
822                 print "contains SIGUSR1\n";
823         }
824 ##########
825 ==POSIX::Termios
826 =new
827 Create a new Termios object.  This object will be destroyed automatically
828 when it is no longer needed.
829
830         $termios = POSIX::Termios->new;
831 =getiflag
832 Retrieve the c_iflag field of a termios object.
833
834         $c_iflag = $termios->getiflag;
835 =getoflag
836 Retrieve the c_oflag field of a termios object.
837
838         $c_oflag = $termios->getoflag;
839 =getcflag
840 Retrieve the c_cflag field of a termios object.
841
842         $c_cflag = $termios->getcflag;
843 =getlflag
844 Retrieve the c_lflag field of a termios object.
845
846         $c_lflag = $termios->getlflag;
847 =getcc
848 Retrieve a value from the c_cc field of a termios object.  The c_cc field is
849 an array so an index must be specified.
850
851         $c_cc[1] = $termios->getcc(1);
852 =getospeed
853 Retrieve the output baud rate.
854
855         $ospeed = $termios->getospeed;
856 =getispeed
857 Retrieve the input baud rate.
858
859         $ispeed = $termios->getispeed;
860 =setiflag
861 Set the c_iflag field of a termios object.
862
863         $termios->setiflag( &POSIX::BRKINT );
864 =setoflag
865 Set the c_oflag field of a termios object.
866
867         $termios->setoflag( &POSIX::OPOST );
868 =setcflag
869 Set the c_cflag field of a termios object.
870
871         $termios->setcflag( &POSIX::CLOCAL );
872 =setlflag
873 Set the c_lflag field of a termios object.
874
875         $termios->setlflag( &POSIX::ECHO );
876 =setcc
877 Set a value in the c_cc field of a termios object.  The c_cc field is an
878 array so an index must be specified.
879
880         $termios->setcc( 1, &POSIX::VEOF );
881 =setospeed
882 Set the output baud rate.
883
884         $termios->setospeed( &POSIX::B9600 );
885 =setispeed
886 Set the input baud rate.
887
888         $termios->setispeed( &POSIX::B9600 );
889 ##
890 =setattr
891 =getattr
892 ##########
893 ==FileHandle
894 =new
895 =new_from_fd
896 =flush
897 =getc
898 =ungetc
899 =seek
900 =setbuf
901 =error
902 =clearerr
903 =tell
904 =getpos
905 =gets
906 =close
907 =new_tmpfile
908 =eof
909 =fileno
910 =setpos
911 =setvbuf
912 ##########
913 ==POSIX
914 =tolower+lc
915 =toupper+uc
916 =remove+unlink
917 =fabs+abs
918 =strstr+index
919 ##
920 =closedir++
921 =readdir++
922 =rewinddir++
923 =fcntl++
924 =getgrgid++
925 =getgrnam++
926 =atan2++
927 =cos++
928 =exp++
929 =abs++
930 =log++
931 =sin++
932 =sqrt++
933 =getpwnam++
934 =getpwuid++
935 =kill++
936 =getc++
937 =rename++
938 =exit++
939 =system++
940 =chmod++
941 =mkdir++
942 =stat++
943 =umask++
944 =gmtime++
945 =localtime++
946 =time++
947 =alarm++
948 =chdir++
949 =chown++
950 =fork++
951 =getlogin++
952 =getpgrp++
953 =getppid++
954 =link++
955 =rmdir++
956 =sleep++
957 =unlink++
958 =utime++
959 ##
960 =perror+C
961 =pause+C
962 =tzset+C
963 =difftime+C
964 =ctime+C
965 =clock+C
966 =asctime+C
967 =strcoll+C
968 =abort+C
969 =tcgetpgrp+C
970 =setsid+C
971 =_exit+C
972 =tanh+C
973 =tan+C
974 =sinh+C
975 =log10+C
976 =ldexp+C
977 =fmod+C
978 =floor+C
979 =cosh+C
980 =ceil+C
981 =atan+C
982 =asin+C
983 =acos+C
984 ##
985 =isatty
986 Returns a boolean indicating whether the specified filehandle is connected
987 to a tty.
988 =setuid
989 Sets the real user id for this process.
990 =setgid
991 Sets the real group id for this process.
992 =getpid
993 Returns the process's id.
994 =getuid
995 Returns the user's id.
996 =getegid
997 Returns the effective group id.
998 =geteuid
999 Returns the effective user id.
1000 =getgid
1001 Returns the user's real group id.
1002 =getgroups
1003 Returns the ids of the user's supplementary groups.
1004 =getcwd
1005 Returns the name of the current working directory.
1006 =strerror
1007 Returns the error string for the specified errno.
1008 =getenv
1009 Returns the value of the specified enironment variable.
1010 =getchar
1011 Returns one character from STDIN.
1012 =raise
1013 Sends the specified signal to the current process.
1014 =gets
1015 Returns one line from STDIN.
1016 =printf
1017 Prints the specified arguments to STDOUT.
1018 =rewind
1019 Seeks to the beginning of the file.
1020 ##
1021 =tmpnam
1022 Returns a name for a temporary file.
1023
1024         $tmpfile = POSIX::tmpnam();
1025 =cuserid
1026 Get the character login name of the user.
1027
1028         $name = POSIX::cuserid();
1029 =ctermid
1030 Generates the path name for controlling terminal.
1031
1032         $path = POSIX::ctermid();
1033 =times
1034 The times() function returns elapsed realtime since some point in the past
1035 (such as system startup), user and system times for this process, and user
1036 and system times used by child processes.  All times are returned in clock
1037 ticks.
1038
1039     ($realtime, $user, $system, $cuser, $csystem) = POSIX::times();
1040
1041 Note: Perl's builtin C<times()> function returns four values, measured in
1042 seconds.
1043 =pow
1044 Computes $x raised to the power $exponent.
1045
1046         $ret = POSIX::pow( $x, $exponent );
1047 =errno
1048 Returns the value of errno.
1049
1050         $errno = POSIX::errno();
1051 =sysconf
1052 Retrieves values of system configurable variables.
1053
1054 The following will get the machine's clock speed.
1055
1056         $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1057 =pathconf
1058 Retrieves the value of a configurable limit on a file or directory.
1059
1060 The following will determine the maximum length of the longest allowable
1061 pathname on the filesystem which holds C</tmp>.
1062
1063         $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX );
1064 =access
1065 Determines the accessibility of a file.
1066
1067         if( POSIX::access( "/", &POSIX::R_OK ) ){
1068                 print "have read permission\n";
1069         }
1070 =setlocale
1071 Modifies and queries program's locale.
1072
1073 The following will set the traditional UNIX system locale behavior.
1074
1075 This document generated by ./mkposixman.PL version 19951212.
1076 ##
1077 =waitpid
1078 =wait
1079 =fstat
1080 =sprintf
1081 =opendir
1082 =creat
1083 =ttyname
1084 =tzname
1085 =fpathconf
1086 =mktime
1087 =tcsendbreak
1088 =tcflush
1089 =tcflow
1090 =tcdrain
1091 =tcsetpgrp
1092 =mkfifo
1093 =strxfrm
1094 =wctomb
1095 =wcstombs
1096 =mbtowc
1097 =mbstowcs
1098 =mblen
1099 =write
1100 =uname
1101 =setpgid
1102 =read
1103 =pipe
1104 =nice
1105 =lseek
1106 =dup2
1107 =dup
1108 =close
1109 =sigsuspend
1110 =sigprocmask
1111 =sigpending
1112 =sigaction
1113 =modf
1114 =frexp
1115 =localeconv
1116 =open
1117 =isxdigit
1118 =isupper
1119 =isspace
1120 =ispunct
1121 =isprint
1122 =isgraph
1123 =isdigit
1124 =iscntrl
1125 =isalpha
1126 =isalnum
1127 =islower
1128 =assert
1129 =strftime
1130 ##########
1131 ==POSIX::SigAction
1132 =new
1133 Creates a new SigAction object.  This object will be destroyed automatically
1134 when it is no longer needed.