Real(3)

💖 Real(3) — FindBin::Real 💖

okay bestie, so this is the manual page for Real(3), aka FindBin::Real, and it's literally the glow-up of FindBin — it tells you where your script actually lives. let's get into it 🫶

---

✨ NAME ✨

FindBin::Real — Locate directory of original perl script

like, the whole personality of this module is "where am i" but for perl scripts. iconic.

---

✨ SYNOPSIS ✨

bestie you have three whole ways to use this, pick your fighter:

use FindBin::Real;
use lib FindBin::Real::Bin() . '/../lib';

or

use FindBin::Real qw(Bin);
use lib Bin() . '/../lib';

or

# Run from /usr/bin/www/some/path/ or /usr/bin/www/some/other/path or any
use FindBin::Real qw(BinDepth);
use lib BinDepth(3) . '/lib';
# And always got /usr/bin/www/lib !

not me being obsessed with that last one — it literally always gets /usr/bin/www/lib no matter which subdirectory you launch from. main character energy fr fr 💅

---

✨ DESCRIPTION ✨

so what it does: it locates the full path to the script bin directory, which lets you use paths relative to the bin directory. no cap, that's the whole vibe.

this means you can set up a directory tree for some software with directories <root>/bin and <root>/lib, and then the example above will let you use modules in the lib directory without knowing where the software tree is installed. 🦋

and one lil edge case: if perl is invoked using the -e option, or the perl script is read from "STDIN", then FindBin sets both Bin() and RealBin() return values to the current directory. periodt.

---

✨ EXPORTABLE FUNCTIONS ✨

here's the whole squad, bestie — every single one:

🌸 Bin

• path to bin directory from where script was invoked

🌸 Script

• basename of script from which perl was invoked

🌸 RealBin

• Bin() with all links resolved

🌸 RealScript

• Script() with all links resolved

🌸 BinDepth(n)

• path to n-level parent directory

🌸 Dir()

• the same as Bin()

🌸 RealDir()

• the same as RealBin()

see? seven little icons, each doing its own thing. we love a functional household ✨

---

✨ KNOWN ISSUES ✨

okay so listen: if there are two modules using FindBin::Real from different directories under the same interpreter, this WOULD work. (yes, the original yells it in all caps, we respect that.)

why? because FindBin::Real uses functions instead of a BEGIN block in FindBin, so it'll be executed on every script, and all callers will get it right. 🎀

that means this module can be used under mod_perl and other persistent Perl environments — where you shouldn't use FindBin. so like, this is the one you want in that situation. iykyk.

---

✨ KNOWN BUGS ✨

okay so there's this one goofy scenario, no hate to anybody involved:

if perl is invoked as

perl filename

and filename does not have executable rights, and a program called filename exists in the users $ENV{PATH} which satisfies both -x and -T — then FindBin assumes that it was invoked via the $ENV{PATH}. 😭 like, it just assumes. rude but understandable.

workaround, bestie: invoke perl as

perl ./filename

and the whole identity crisis is avoided. you're welcome 💀

---

✨ AUTHORS ✨

Serguei Trouchelle <stro@railways.dp.ua>

also, FindBin::Real uses code from the FindBin module, which was written by:

Graham Barr <gbarr@pobox.com> Nick Ing-Simmons <nik@tiuk.ti.com>

king behaviour from all three, honestly 👑

---

✨ COPYRIGHT ✨

Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved. Copyright (c) 2003-2005 Serguei Trouchelle. All rights reserved.

and the legal bit, verbatim because bestie we do not mess with license text:

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page! 🎀 this was Real(3) from perl v5.42.0, dated 2011-11-18 — vintage but still slaying, mwah 💋✨