NAME

       Net::FastCGI::IO - Provides functions to read and write FastCGI messages.

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);

DESCRIPTION

       Provides unbuffered blocking I/O functions to read and write FastCGI messages.

FUNCTIONS

   read_header
       Attempts to read a "FCGI_Header" from file handle $fh.

       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};

       Arguments

       $fh The file handle to read from. Must be a file handle with a file descriptor. File
           handle mode should be set to binary.

       Returns

       Upon successful completion, the return value of "parse_header" in Net::FastCGI::Protocol.
       Otherwise, a false value ("undef" in scalar context and an empty list in list context).

       If "read_header" reaches end-of-file before reading any octets, it returns a false value.
       If unsuccessful, "read_header" returns a false value and $!  contains the error from the
       "sysread" call. If "read_header" encounters end-of-file after some but not all of the
       needed octets, the function returns a false value and sets $! to "EPIPE".

       Implementation

       The implementation calls "sysread" in a loop, restarting if "sysread" returns "undef" with
       $! set to "EINTR". If "sysread" does not provide all the requested octets, "read_header"
       continues to call "sysread" until either all the octets have been read, reaches end-of-
       file or an error occurs.

   read_record
       Attempts to read a "FCGI_Record" from file handle $fh.

       Usage

           ($type, $request_id, $content)
             = read_record($fh);

           $record = read_record($fh);
           say $record->{type};
           say $record->{request_id};

       Arguments

       $fh The file handle to read from. Must be a file handle with a file descriptor.  File
           handle mode should be set to binary.

       Returns

       Upon successful completion, the return value of "parse_record" in Net::FastCGI::Protocol.
       Otherwise, a false value ("undef" in scalar context and an empty list in list context).

       If "read_record" reaches end-of-file before reading any octets, it returns a false value.
       If unsuccessful, "read_record" returns a false value and $!  contains the error from the
       "sysread" call. If "read_record" encounters end-of-file after some but not all of the
       needed octets, the function returns a false value and sets $! to "EPIPE".

       Implementation

       The implementation calls "sysread" in a loop, restarting if "sysread" returns "undef" with
       $! set to "EINTR". If "sysread" does not provide all the requested octets, "read_record"
       continues to call "sysread" until either all the octets have been read, reaches end-of-
       file or an error occurs.

   write_header
       Attempts to write a "FCGI_Header" to file handle $fh.

       Usage

           $result = write_header($fh, $type, $request_id, $content_length, $padding_length);

       Arguments

       $fh The file handle to write to. Must be a file handle with a file descriptor. File handle
           mode should be set to binary.

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content_length
           An unsigned 16-bit integer.

       $padding_length
           An unsigned 8-bit integer.

       Returns

       $result
           Upon successful completion, the number of octets actually written. Otherwise, "undef"
           and $! contains the error from the "syswrite" call.

       Implementation

       The implementation calls "syswrite" in a loop, restarting if "syswrite" returns "undef"
       with $! set to "EINTR". If "syswrite" does not output all the requested octets,
       "write_header" continues to call "syswrite" until all the octets have been written or an
       error occurs.

   write_record
       Attempts to write a "FCGI_Record" to file handle $fh.

       Usage

           $result = write_record($fh, $type, $request_id);
           $result = write_record($fh, $type, $request_id, $content);

       Arguments

       $fh The file handle to write to. Must be a file handle with a file descriptor. File handle
           mode should be set to binary.

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content (optional)
           A string of octets containing the content, cannot exceed 65535 octets in length.

       Returns

       $result
           Upon successful completion, the number of octets actually written. Otherwise, "undef"
           and $! contains the error from the "syswrite" call.

       Implementation

       The implementation calls "syswrite" in a loop, restarting if "syswrite" returns "undef"
       with $! set to "EINTR". If "syswrite" does not output all the requested octets,
       "write_record" continues to call "syswrite" until all the octets have been written or an
       error occurs.

   write_stream
       Attempts to write a "FCGI_Record" stream to file handle $fh.

       Usage

           $result = write_stream($fh, $type, $request_id, $content);
           $result = write_stream($fh, $type, $request_id, $content, $terminate);

       Arguments

       $fh The file handle to write to. Must be a file handle with a file descriptor. File handle
           mode should be set to binary.

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content
           A string of octets containing the stream content.

       $terminate (optional)
           A boolean indicating whether or not the stream should be terminated.  Defaults to
           false.

       Returns

       $result
           Upon successful completion, the number of octets actually written. Otherwise, "undef"
           and $! contains the error from the "syswrite" call.

       Implementation

       The implementation calls "syswrite" in a loop, restarting if "syswrite" returns "undef"
       with $! set to "EINTR". If "syswrite" does not output all the requested octets,
       "write_stream" continues to call "syswrite" until all the octets have been written or an
       error occurs.

   can_read
       Determines whether or not the given file handle $fh is ready for reading within the given
       timeout $timeout.

       Usage

           $result = can_read($fh, $timeout);

       Arguments

       $fh The file handle to test for readiness. Must be a file handle with a file descriptor.

       $timeout
           Maximum interval to wait. Can be set to either a non-negative numeric value or "undef"
           for infinite wait.

       Returns

       Upon successful completion, 0 or 1. Otherwise, "undef" and $! contains the "select" error.

       Implementation

       The implementation calls "select" in a loop, restarting if "select" returns "-1" with $!
       set to "EINTR" and $timeout has not elapsed.

   can_write
       Determines whether or not the given file handle $fh is ready for writing within the given
       timeout $timeout.

       Usage

           $result = can_write($fh, $timeout);

       Arguments

       $fh The file handle to test for readiness. Must be a file handle with a file descriptor.

       $timeout
           Maximum interval to wait. Can be set to either a non-negative numeric value or "undef"
           for infinite wait.

       Returns

       Upon successful completion, 0 or 1. Otherwise, "undef" and $! contains the "select" error.

       Implementation

       The implementation calls "select" in a loop, restarting if "select" returns "-1" with $!
       set to "EINTR" and $timeout has not elapsed.

EXPORTS

       None by default. All functions can be exported using the ":all" tag or individually.

DIAGNOSTICS

       (F) Usage: %s
           Subroutine called with wrong number of arguments.

       (W Net::FastCGI::IO) FastCGI: Could not read %s
       (W Net::FastCGI::IO) FastCGI: Could not write %s

SEE ALSO

       FastCGI Specification Version 1.0
           <http://www.fastcgi.com/devkit/doc/fcgi-spec.html>

       The Common Gateway Interface (CGI) Version 1.1
           <http://tools.ietf.org/html/rfc3875>

       Net::FastCGI::Constant
       Net::FastCGI::Protocol

AUTHOR

       Christian Hansen "chansen@cpan.org"

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.