--- name: "Net::FastCGI::IO" section: "3pm" platform: "linux" package: "libnet-fastcgi-perl" version: "0.14-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::FastCGI::IO" --- # Net::FastCGI::IO(3pm) Provides functions to read and write FastCGI messages. ## 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 \ - The Common Gateway Interface (CGI) Version 1.1 \ - 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.