=head1 NAME
Net::FastCGI::IO - Provides functions to read and write FastCGI messages.
=head1 SYNOPSIS
# FCGI_Header
@values = read_header($fh);
$header = read_header($fh);
$result = write_header($fh, $type, $request_id, $content_length, $padding_length);
# FCGI_Record
@values = read_record($fh);
$record = read_record($fh);
$result = write_record($fh, $type, $request_id);
$result = write_record($fh, $type, $request_id, $content);
# FCGI_Record Stream
$result = write_stream($fh, $type, $request_id, $content);
$result = write_stream($fh, $type, $request_id, $content, $terminate);
# I/O ready
$result = can_read($fh, $timeout);
$result = can_write($fh, $timeout);
=head1 DESCRIPTION
Provides unbuffered blocking I/O functions to read and write FastCGI messages.
=head1 FUNCTIONS
=head2 read_header
Attempts to read a C<FCGI_Header> from file handle C<$fh>.
I<Usage>
($type, $request_id, $content_length, $padding_length)
= read_header($fh);
$header = read_header($fh);
say $header->{type};
say $header->{request_id};
say $header->{content_length};
say $header->{padding_length};
I<Arguments>
=over 4
=item C<$fh>
The file handle to read from. Must be a file handle with a file descriptor. File handle
mode should be set to binary.
=back
I<Returns>
Upon successful completion, the return value of L<Net::FastCGI::Protocol/parse_header>.
Otherwise, a false value (C<undef> in scalar context and an empty list in list context).
If C<read_header> reaches end-of-file before reading any octets, it returns a
false value. If unsuccessful, C<read_header> returns a false value and C<$!>
contains the error from the C<sysread> call. If C<read_header> encounters
end-of-file after some but not all of the needed octets, the function returns
a false value and sets C<$!> to C<EPIPE>.
I<Implementation>
The implementation calls C<sysread> in a loop, restarting if C<sysread>
returns C<undef> with C<$!> set to C<EINTR>. If C<sysread> does not provide
all the requested octets, C<read_header> continues to call C<sysread> until
either all the octets have been read, reaches end-of-file or an error occurs.
=head2 read_record
Attempts to read a C<FCGI_Record> from file handle C<$fh>.
I<Usage>
($type, $request_id, $content)
= read_record($fh);
$record = read_record($fh);
say $record->{type};
say $record->{request_id};
I<Arguments>
=over 4
=item C<$fh>
The file handle to read from. Must be a file handle with a file descriptor.
File handle mode should be set to binary.
=back
I<Returns>
Upon successful completion, the return value of L<Net::FastCGI::Protocol/parse_record>.
Otherwise, a false value (C<undef> in scalar context and an empty list in list context).
If C<read_record> reaches end-of-file before reading any octets, it returns a
false value. If unsuccessful, C<read_record> returns a false value and C<$!>
contains the error from the C<sysread> call. If C<read_record> encounters
end-of-file after some but not all of the needed octets, the function returns
a false value and sets C<$!> to C<EPIPE>.
I<Implementation>
The implementation calls C<sysread> in a loop, restarting if C<sysread>
returns C<undef> with C<$!> set to C<EINTR>. If C<sysread> does not provide
all the requested octets, C<read_record> continues to call C<sysread> until
either all the octets have been read, reaches end-of-file or an error occurs.
=head2 write_header
Attempts to write a C<FCGI_Header> to file handle C<$fh>.
I<Usage>
$result = write_header($fh, $type, $request_id, $content_length, $padding_length);
I<Arguments>
=over 4
=item C<$fh>
The file handle to write to. Must be a file handle with a file descriptor. File handle
mode should be set to binary.
=item C<$type>
An unsigned 8-bit integer.
=item C<$request_id>
An unsigned 16-bit integer.
=item C<$content_length>
An unsigned 16-bit integer.
=item C<$padding_length>
An unsigned 8-bit integer.
=back
I<Returns>
=over 4
=item C<$result>
Upon successful completion, the number of octets actually written. Otherwise,
C<undef> and C<$!> contains the error from the C<syswrite> call.
=back
I<Implementation>
The implementation calls C<syswrite> in a loop, restarting if C<syswrite>
returns C<undef> with C<$!> set to C<EINTR>. If C<syswrite> does not output
all the requested octets, C<write_header> continues to call C<syswrite> until
all the octets have been written or an error occurs.
=head2 write_record
Attempts to write a C<FCGI_Record> to file handle C<$fh>.
I<Usage>
$result = write_record($fh, $type, $request_id);
$result = write_record($fh, $type, $request_id, $content);
I<Arguments>
=over 4
=item C<$fh>
The file handle to write to. Must be a file handle with a file descriptor. File handle
mode should be set to binary.
=item C<$type>
An unsigned 8-bit integer.
=item C<$request_id>
An unsigned 16-bit integer.
=item C<$content> (optional)
A string of octets containing the content, cannot exceed 65535 octets in length.
=back
I<Returns>
=over 4
=item C<$result>
Upon successful completion, the number of octets actually written. Otherwise,
C<undef> and C<$!> contains the error from the C<syswrite> call.
=back
I<Implementation>
The implementation calls C<syswrite> in a loop, restarting if C<syswrite>
returns C<undef> with C<$!> set to C<EINTR>. If C<syswrite> does not output
all the requested octets, C<write_record> continues to call C<syswrite> until
all the octets have been written or an error occurs.
=head2 write_stream
Attempts to write a C<FCGI_Record> stream to file handle C<$fh>.
I<Usage>
$result = write_stream($fh, $type, $request_id, $content);
$result = write_stream($fh, $type, $request_id, $content, $terminate);
I<Arguments>
=over 4
=item C<$fh>
The file handle to write to. Must be a file handle with a file descriptor. File handle
mode should be set to binary.
=item C<$type>
An unsigned 8-bit integer.
=item C<$request_id>
An unsigned 16-bit integer.
=item C<$content>
A string of octets containing the stream content.
=item C<$terminate> (optional)
A boolean indicating whether or not the stream should be terminated.
Defaults to false.
=back
I<Returns>
=over 4
=item C<$result>
Upon successful completion, the number of octets actually written. Otherwise,
C<undef> and C<$!> contains the error from the C<syswrite> call.
=back
I<Implementation>
The implementation calls C<syswrite> in a loop, restarting if C<syswrite>
returns C<undef> with C<$!> set to C<EINTR>. If C<syswrite> does not output
all the requested octets, C<write_stream> continues to call C<syswrite> until
all the octets have been written or an error occurs.
=head2 can_read
Determines wheter or not the given file handle C<$fh> is ready for reading
within the given timeout C<$timeout>.
I<Usage>
$result = can_read($fh, $timeout);
I<Arguments>
=over 4
=item C<$fh>
The file handle to test for readiness. Must be a file handle with a file descriptor.
=item C<$timeout>
Maximum interval to wait. Can be set to either a non-negative numeric value or
C<undef> for infinite wait.
=back
I<Returns>
Upon successful completion, C<0> or C<1>. Otherwise, C<undef> and C<$!> contains
the C<select> error.
I<Implementation>
The implementation calls C<select> in a loop, restarting if C<select> returns
C<-1> with C<$!> set to C<EINTR> and C<$timeout> has not elapsed.
=head2 can_write
Determines wheter or not the given file handle C<$fh> is ready for writing
within the given timeout C<$timeout>.
I<Usage>
$result = can_write($fh, $timeout);
I<Arguments>
=over 4
=item C<$fh>
The file handle to test for readiness. Must be a file handle with a file descriptor.
=item C<$timeout>
Maximum interval to wait. Can be set to either a non-negative numeric value or
C<undef> for infinite wait.
=back
I<Returns>
Upon successful completion, C<0> or C<1>. Otherwise, C<undef> and C<$!> contains
the C<select> error.
I<Implementation>
The implementation calls C<select> in a loop, restarting if C<select> returns
C<-1> with C<$!> set to C<EINTR> and C<$timeout> has not elapsed.
=head1 EXPORTS
None by default. All functions can be exported using the C<:all> tag or individually.
=head1 DIAGNOSTICS
=over 4
=item B<(F)> Usage: %s
Subroutine called with wrong number of arguments.
=item B<(W Net::FastCGI::IO)> FastCGI: Could not read %s
=item B<(W Net::FastCGI::IO)> FastCGI: Could not write %s
=back
=head1 SEE ALSO
=over 4
=item FastCGI Specification Version 1.0
L<http://www.fastcgi.com/devkit/doc/fcgi-spec.html>
=item The Common Gateway Interface (CGI) Version 1.1
L<http://tools.ietf.org/html/rfc3875>
=item L<Net::FastCGI::Constant>
=item L<Net::FastCGI::Protocol>
=back
=head1 AUTHOR
Christian Hansen C<chansen@cpan.org>
=head1 COPYRIGHT
Copyright 2008-2010 by Christian Hansen.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.