Net::FastCGI::IO(3pm)

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.