Net::FastCGI::IO(3pm)

💖 Net::FastCGI::IO 💖

okay bestie, so this is Net::FastCGI::IO from the User Contributed Perl Documentation — it's a Perl module and it hands you a whole lil toolbox of functions for reading and writing FastCGI messages. that's the whole vibe. no cap. 🦋

---

✨ 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 🌸

so basically, this module gives you unbuffered blocking I/O functions to read and write FastCGI messages. that's it, that's the whole thing, and honestly? iconic. 🎀

---

💅 FUNCTIONS 💅

🌈 read_header

it's gonna attempt to read a FCGI_Header from the file handle $fh. slay.

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 you're reading from. it must be a file handle with a file descriptor, and ngl the file handle mode should be set to binary. fr fr.

Returns

upon successful completion, you get the return value of parse_header in Net::FastCGI::Protocol. otherwise you get 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 it's unsuccessful, read_header returns a false value and $! contains the error from the sysread call.
• if read_header hits 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 doesn't provide all the requested octets, read_header keeps calling sysread until either all the octets have been read, it reaches end-of-file, or an error occurs. lowkey relentless. 💪

🌈 read_record

attempts to read a FCGI_Record from file handle $fh. bestie it's giving "record read."

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

same energy as above: sysread in a loop, restarting if sysread returns undef with $! set to EINTR. if sysread doesn't provide all the requested octets, read_record continues to call sysread until either all the octets have been read, it reaches end-of-file, or an error occurs. ✨

🌈 write_header

attempts to write a FCGI_Header to file handle $fh. yes queen, write it. ✍️

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 doesn't 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, and it cannot exceed 65535 octets in length. that's a hard limit bestie, respect it. 🚫

Returns

• $result — upon successful completion, the number of octets actually written. otherwise, undef and $! contains the error from the syswrite call.

Implementation

syswrite in a loop, restarting if syswrite returns undef with $! set to EINTR. if syswrite doesn't 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. stream mode activated. 🌊

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

you already know: syswrite in a loop, restarting if syswrite returns undef with $! set to EINTR. if syswrite doesn't 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. vibe check on your file handle, essentially. 👀

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. the sibling of can_read, equally iconic. 💜

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, sorry bestie. all functions can be exported using the :all tag or individually. your call, main character. 💅

---

🚨 DIAGNOSTICS 🚨

• (F) Usage: %s — subroutine called with wrong number of arguments. bestie. count your args. 😭
• (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.

---

okay that's the whole page, we ate and left no crumbs 🍓✨ this was perl v5.36.0, dated 2022-11-21, and the page is Net::FastCGI::IO(3pm) — mwah, bye bestie 💖🧚