FDPass(3pm)

💖 FDPass — like, the whole vibe 💖

okay bestie, listen. this is IO::FDPass, a perl module from the User Contributed Perl Documentation crew, and it does exactly one (1) thing and it does it iconicly. sit down, get comfy 🫶

---

✨ NAME ✨

IO::FDPass — bestie... it passes a file descriptor over a socket. that's it. that's the whole job. no cap 💅

---

✨ SYNOPSIS ✨

okay so this is literally all you need to know:

use IO::FDPass;

IO::FDPass::send fileno $socket, fileno $fh_to_pass
   or die "send failed: $!";

my $fd = IO::FDPass::recv fileno $socket;
$fd >= 0 or die "recv failed: $!";

periodt. 🎀

---

✨ DESCRIPTION ✨

ngl this tiny low-level module has one singular purpose: hand a file descriptor over to another process. that's it. how? via a (streaming) unix domain socket on POSIX systems, or literally any (streaming) socket on WIN32 systems. 🌈

and the ability to pass file descriptors on windows?? that is currently the unique selling point of this module ✨👑 yes i said it. and did i mention it's really small too? because it's really small. like really small. 🦋

---

✨ FUNCTIONS ✨

💫 $bool = IO::FDPass::send $socket_fd, $fd_to_pass

sends the file descriptor given by $fd_to_pass over the socket $socket_fd. returns true if it worked, false otherwise. slay or flop, no in-between. 💀

⚠️ heads up bestie: both parameters must be file descriptors, not handles. fr fr. handles will not fly here.

when you use this on non-blocking sockets, this function might fail with $! set to "EAGAIN" or equivalent — and in that case you're free to try again! it should succeed if you call it on a socket that indicates writability (e.g. via "select"). 👑

example — pass a file handle over an open socket:

IO::FDPass::send fileno $socket, fileno $fh
   or die "unable to pass file handle: $!";

💫 $fd = IO::FDPass::recv $socket_fd

receive a file descriptor from the socket and return it if it went well. on errors? it returns -1. 😭 so check that number, bestie.

⚠️ and again: both $socket_fd and the returned file descriptor are, in fact, file descriptors, not handles. i cannot stress this enough.

when you use this on non-blocking sockets, this function might fail with $! set to "EAGAIN" or equivalent, in which case you're free to try again. it should succeed if called on a socket that indicates readability (e.g. via "select"). 💅

example — receive a file descriptor from a blocking socket and convert it to a file handle:

my $fd = IO::FDPass::recv fileno $socket;
$fd >= 0 or die "unable to receive file handle: $!";
open my $fh, "+<&=$fd"
   or die "unable to convert file descriptor to handle: $!";

---

✨ PORTABILITY NOTES ✨

okay this is the part where the receipts come out 📜✨ this module has been tested on, and found to work on:

• GNU/Linux x86 and amd64
• NetBSD 6
• OS X 10.5
• Windows 2000 ActivePerl 5.10
• Solaris 10
• OpenBSD 4.4, 4.5, 4.8 and 5.0
• DragonFly BSD
• FreeBSD 7, 8 and 9
• Windows 7 + ActivePerl 5.16.3 32 and 64 bit
• Strawberry Perl 5.16.3 32 and 64 bit

...although heads up: ActivePerl 32 bit needed a newer MinGW version (one that supports XP and higher). 🙈

however — and this is the big one — windows doesn't support asynchronous file descriptor passing, so the source process must still be around when the destination process wants to receive the file handle. 💀 also, if the target process fails to fetch the handle for any reason (crashes, fails to call "recv", etc.), the handle will leak — so literally never do that. i'm so serious. 😭

also, on windows, the receiving process must have the PROCESS_DUP_HANDLE access right on the sender process for this module to work. that's the price of entry, babe. 🎀

Cygwin is not supported at the moment, because file descriptor passing in cygwin isn't supported, and you cannot roll it on your own either, since cygwin has no (working) method of opening a handle as fd. okay so technically it has one, but that one isn't exposed to programs, and it's only used for stdin/out/err. sigh. 💀

---

✨ OTHER MODULES ✨

at the time of this writing, the author of this module was aware of two other file descriptor passing modules on CPAN: File::FDPasser and AnyEvent::FDPasser. let's spill the tea ☕

• File::FDPasser — hasn't seen any release for over a decade, isn't 64 bit clean, and its author didn't respond to the author's mail with the fix, so it doesn't work on many 64 bit machines. 😭 it does, however, support a number of pre-standard unices — basically everything of relevance at the time it was written. vintage, bestie.
• AnyEvent::FDPasser — seems to have similar support for antique unices, and doesn't seem to suffer from 64 bit bugs. but inexplicably it has a large perl part, doesn't support mixing data and file descriptors, and requires AnyEvent. 🙈 presumably that makes it much more user friendly than this module — skimming the manpage shows a lot of thought has gone into it, and you're well advised to read it and maybe use it before trying a low-level module such as this one. in fact, that manpage discusses even more file descriptor passing modules on CPAN. the lore runs deep 🌈

neither of them seems to support native win32 perls, fyi. 🦋

---

✨ AUTHOR ✨

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/

---

and that's the whole page, bestie 💖 this little cutie ships with perl v5.42.3 and the date on it is 2026-08-19 — like, that's FDPass(3pm) in its final form. go forth and pass those file descriptors. you got this. 🫶✨🎀