=begin pod

=TITLE class IO::Special

=SUBTITLE Represent a Standard I/O device

This provides a similar interface for the special standard input and output
handles C<$*IN>, C<$*OUT> and C<$*ERR> to that of L<IO::Path|/type/IO::Path>
for regular files.  It is typically returned by the L<path method|/type/IO::Handle#method_path>
of those handles so that they can be used interchangeably with the handles of
regular files.

=head1 Methods

=head2 method new

=for code :skip-test
method new(:$!what!)

The constructor has a single required named argument C<what> that will be
'<STDIN>', '<STDOUT>' or '<STDERR>' as appropriate.  It is unlikely that you
will ever need to construct one of these objects yourself however as it
will be done for you when the special handles are initialised.

=head2 method WHICH

    method WHICH(IO::Special:D:) returns Str

This returns a string which identifies the object.

=head2 method Str

    method Str(IO::Special:D:)

This returns '<STDIN>', '<STDOUT>' or '<STDERR>' as appropriate.

=head2 method IO

    method IO(IO::Special:D:) returns IO::Special

This returns the C<IO::Special> object, it is provided for
conformance to the C<IO::Path> interface.

=head2 method e

    method e(IO::Special:D:) returns Bool

The 'exists' file test operator, always returns C<True>.

=head2 method d

    method d(IO::Special:D:) returns Bool

The 'directory' file test operator, always returns C<False>.

=head2 method f

    method f(IO::Special:D:) returns Bool

The 'file' file test operator, always returns C<False>.

=head2 method s

    method s(IO::Special:D:) returns Int

The 'size' file test operator, always returns 0.

=head2 method l

    method l(IO::Special:D:) returns Bool

The 'symbolic links' file test operator, always returns C<False>.

=head2 method r

    method r(IO::Special:D:) returns Bool

The 'read access' file test operator, returns C<True> if this is
the standard input handle, C<False> otherwise.

=head2 method w

    method w(IO::Special:D:) returns Bool

The 'write access' file test operator, returns C<True> if this is
the standard output or standard error handle, C<False> if it is
the standard input.


=head2 method x

    method x(IO::Special:D:) returns Bool

The 'execute access' file test operator, always returns C<False>.


=head2 method modified

    method modified(IO::Special:D:) returns Instant

The last modified time always returns an undefined L<Instant>.

=head2 method accessed

    method accessed(IO::Special:D:) returns Instant

The last accessed time always returns an undefined L<Instant>

=head2 method changed

    method changed(IO::Special:D:) returns Instant

The last changed time always returns an undefined L<Instant>

=head2 method mode

    method mode(IO::Special:D:) returns Nil

The mode always returns L<Nil>

=end pod
