[p5sagit/p5-mst-13.2.git] / lib / perlio.pm

package perlio;
1;
__END__

=head1 NAME

perlio - perl pragma to configure C level IO

=head1 SYNOPSIS

  Shell:
    PERLIO=perlio perl ....

    print "Have ",join(',',keys %perlio::layers),"\n";
    print "Using ",join(',',@perlio::layers),"\n";


=head1 DESCRIPTION

Mainly a Place holder for now.

The C<%perlio::layers> hash is a record of the available "layers" that may be pushed
onto a C<PerlIO> stream.

The C<@perlio::layers> array is the current set of layers that are used when
a new C<PerlIO> stream is opened. The C code looks are the array each time
a stream is opened so the "stack" can be manipulated by messing with the array :

    pop(@perlio::layers);
    push(@perlio::layers,$perlio::layers{'stdio'});

The values if both the hash and the array are perl objects, of class C<perlio::Layer>
which are created by the C code in C<perlio.c>. As yet there is nothing useful you
can do with the objects at the perl level.

There are three layers currently defined:

=over 4

=item unix

Low level layer which calls C<read>, C<write> and C<lseek> etc.

=item stdio

Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.
Note that as this is "real" stdio it will ignore any layers beneath it and
got straight to the operating system via the C library as usual.

=item perlio

This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer".
As such it will call whatever layer is below it for its operations.

=back

=head2 Defaults and how to override them

If C<Configure> found out how to do "fast" IO using system's stdio, then
the default layers are :

  unix stdio

Otherwise the default layers are

  unix perlio

(STDERR will have just unix in this case as that is optimal way to make it
"unbuffered" - do not add a buffering layer!)

The default may change once perlio has been better tested and tuned.

The default can be overridden by setting the environment variable PERLIO
to a space separated list of layers (unix is always pushed first).
This can be used to see the effect of/bugs in the various layers e.g.

  cd .../perl/t
  PERLIO=stdio  ./perl harness
  PERLIO=perlio ./perl harness

=head1 AUTHOR

Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>

=cut
Commit	Line	Data
f3862f8b	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