Provided by: libnet-fastcgi-perl_0.14-2_all 
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.
perl v5.36.0 2022-11-21 Net::FastCGI::IO(3pm)