lib/perlio.pm

   1 package perlio;
   2 1;
   3 __END__
   4
   5 =head1 NAME
   6
   7 perlio - perl pragma to configure C level IO
   8
   9 =head1 SYNOPSIS
  10
  11   Shell:
  12     PERLIO=perlio perl ....
  13
  14     print "Have ",join(',',keys %perlio::layers),"\n";
  15     print "Using ",join(',',@perlio::layers),"\n";
  16
  17
  18 =head1 DESCRIPTION
  19
  20 Mainly a Place holder for now.
  21
  22 The C<%perlio::layers> hash is a record of the available "layers" that may be pushed
  23 onto a C<PerlIO> stream.
  24
  25 The C<@perlio::layers> array is the current set of layers that are used when
  26 a new C<PerlIO> stream is opened. The C code looks are the array each time
  27 a stream is opened so the "stack" can be manipulated by messing with the array :
  28
  29     pop(@perlio::layers);
  30     push(@perlio::layers,$perlio::layers{'stdio'});
  31
  32 The values if both the hash and the array are perl objects, of class C<perlio::Layer>
  33 which are created by the C code in C<perlio.c>. As yet there is nothing useful you
  34 can do with the objects at the perl level.
  35
  36 There are three layers currently defined:
  37
  38 =over 4
  39
  40 =item unix
  41
  42 Low level layer which calls C<read>, C<write> and C<lseek> etc.
  43
  44 =item stdio
  45
  46 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.
  47 Note that as this is "real" stdio it will ignore any layers beneath it and
  48 got straight to the operating system via the C library as usual.
  49
  50 =item perlio
  51
  52 This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer".
  53 As such it will call whatever layer is below it for its operations.
  54
  55 =back
  56
  57 =head2 Defaults and how to override them
  58
  59 If C<Configure> found out how to do "fast" IO using system's stdio, then
  60 the default layers are :
  61
  62   unix stdio
  63
  64 Otherwise the default layers are
  65
  66   unix perlio
  67
  68 (STDERR will have just unix in this case as that is optimal way to make it
  69 "unbuffered" - do not add a buffering layer!)
  70
  71 The default may change once perlio has been better tested and tuned.
  72
  73 The default can be overridden by setting the environment variable PERLIO
  74 to a space separated list of layers (unix is always pushed first).
  75 This can be used to see the effect of/bugs in the various layers e.g.
  76
  77   cd .../perl/t
  78   PERLIO=stdio  ./perl harness
  79   PERLIO=perlio ./perl harness
  80
  81 =head1 AUTHOR
  82
  83 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
  84
  85 =cut
  86
  87