Commit | Line | Data |
760ac839 |
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. |