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.