File::Policy(3pm)

💖 File::Policy(3pm) 💖

okay bestie, sit down, we're talking about File::Policy — the manual page, the whole vibe, the site policy for file I/O functions. it's giving sysadmin-with-a-plan energy and honestly? iconic. 🎀

---

✨ NAME ✨

File::Policy — site policy for file I/O functions. no cap, that's the whole job description.

---

🌸 SYNOPSIS 🌸

use File::Policy;
use File::Policy qw/check_safe/;   # to import a specific subroutine
use File::Policy qw/:all/;         # to import all subroutines

#Checking I/O policy
check_safe($filename, 'r');
check_safe($filename, 'w');

#Preferred directory locations
$logdir = get_log_dir();
$tmpdir = get_temp_dir();

like... you can pull in just check_safe, or you can pull in the whole squad with :all. your call, main character. 💅

---

🦋 DESCRIPTION 🦋

so this module defines the policy for file I/O for stuff like File::Slurp::WithinPolicy. the whole point? it lets sysadmins define where apps are allowed to do file I/O and what restrictions apply, and then it hands app developers a policy to follow. 🫶

⚠️ huge disclaimer bestie: this module does not ENFORCE the policy. application developers can absolutely choose to ignore it — and systems administrators can choose not to install their applications if they do! 😭 balance.

you get to control which policy actually gets applied by making a File::Policy::Config module with an IMPLEMENTATION constant. and yes, you can absolutely write your own policy as a module inside the File::Policy:: namespace. go off. ✨

by default — meaning if there's no File::Policy::Config hanging around — the File::Policy::Default policy gets applied. and that one imposes zero restrictions and just gives you reasonable default locations for temporary and log files. chill. no drama. 🌈

the motivation behind this whole module was to have a standard, flexible approach so a site-wide file policy can be defined. this is most useful in big environments where a few sysadmins are responsible for code written by a whole crowd of other people. just making sure submitted code calls check_safe() keeps file access sane, which means way less effort spent on a security audit. it's giving delegation, it's giving boundaries, we love to see it. 👑

if your code isn't security-audit'd, or you're literally the only developer at your site, this might be overkill. but lowkey you could still consider it good practise anyway — it's protection against paths in your code getting corrupted accidentally or maliciously down the line. future-proofing, bestie. 💜

there are two major benefits of using this module:

1. sites that do implement a policy can more easily integrate your code in a standard way.
2. if you have a file policy at your site, you can apply different policies (via File::Policy::Config) in different environments — production, integration test, development — and the appropriate policy is automatically applied without you having to change your code or your configs. periodt. 💅

---

💅 FUNCTIONS 💅

🍓 check_safe

check_safe( FILENAME , MODE );

checks that FILENAME is safe — and dies if it's not. 😭 MODE is r (read) or w (write). that's it, that's the function.

🍓 get_temp_dir

$temporary_directory = get_temp_dir();

returns the path to the temporary directory. heads up tho: any return value will have been cleared of a trailing slash. so no sneaky / at the end. ✨

🍓 get_log_dir

$log_directory = get_log_dir();

returns the path to the log directory. same deal — any return value will have been cleared of a trailing slash. 💖

---

🧚 DEFINING YOUR OWN POLICY 🧚

want your own custom policy? obsessed, let's do it:

cp File/Policy/Default.pm File/Policy/YourPolicy.pm

then modify YourPolicy accordingly. next, create File/Policy/Config.pm containing:

use constant IMPLEMENTATION => 'YourPolicy';

and now, once you've used File::Policy, calling check_safe in your scripts will enforce your policy — plus it hands you access to log and temp paths in the locations you recommend. slay. 🔥

---

🌈 SEE ALSO 🌈

File::Policy::Default, Safe

---

⭐ VERSION ⭐

$Revision: 1.5 $ on $Date: 2005/05/18 15:58:21 $ by $Author: johna $

---

👑 AUTHOR 👑

John Alden <cpan _at_ bbc _dot_ co _dot_ uk>

---

💜 COPYRIGHT 💜

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

---

and that's the whole page, bestie 🫶 this was rendered from perl v5.36.0 dated 2022-12-07 — yes, a whole elder of a manual page, still serving looks. mwah. 💖✨🎀