/ 
Net-FastCGI-0.14
River stage two • 4 direct dependents • 10 total dependents
/ Net::FastCGI::IO

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 wheter 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 wheter 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.