File-Save-Home-0.12/0000755000175000017500000000000015126332102013700 5ustar jkeenanjkeenanFile-Save-Home-0.12/META.json0000664000175000017500000000310315126332102015320 0ustar jkeenanjkeenan{ "abstract" : "Place file safely under user home directory", "author" : [ "James E Keenan (jkeenan@cpan.org)" ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.76, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "File-Save-Home", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "Carp" : "0", "File::Find" : "0", "File::Path" : "0", "File::Spec" : "0", "File::Temp" : "0", "Test::Simple" : "0.44" } }, "test" : { "requires" : { "String::Random" : "0" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=File-Save-Home" }, "homepage" : "http://thenceforward.net/perl/modules/File-Save-Home/", "repository" : { "type" : "git", "url" : "https://github.com/jkeenan/file-save-home.git", "web" : "https://github.com/jkeenan/file-save-home" } }, "version" : "0.12", "x_serialization_backend" : "JSON::PP version 4.16" } File-Save-Home-0.12/Changes0000644000175000017500000000547613174471172015223 0ustar jkeenanjkeenanChanges for Perl extension File::Save::Home 0.11 Thu Oct 26 19:37:27 EDT 2017 Document limitations with regard to TOCTTOU problems. In tests, use String::Random rather than String::PerlIdentifier, thereby easing maintenance burdens for Debian Perl group. No changes in functionality. 0.10 Fri Feb 10 21:25:41 EST 2017 Move into git for version control. Establish github.com repository. In restore_subhome_directory_status(), die rather than simply warning when a directory or file can not be found for removal. More use of catdir and catfile to compose paths. 0.09 Fri Dec 14 19:34:00 EXT 2012 Two spelling corrections reported by Xavier Guimard. 0.08 Wed Feb 22 22:14:24 EST 2006 Modified get_subhome_directory_status() and make_subhome_temp_directory() so that each takes an optional additional argument which is name of a valid directory which user wishes to use as a ''pseudo-home-directory'' in place of the output of get_home_directory(). Wrote t/05_pseudohome.t to test this revised functionality. Wrote t/06_Win32.t to make sure that this functionality works with File::HomeDir::my_home() on Windows. 0.07 Fri Feb 17 19:42:05 EST 2006 No change in functionality. At suggestion of Rob Rothenberg, expanded documentation, particularly in ''SEE ALSO'' section, to reference other CPAN distributions which try to locate a user's home directory. 0.06 Fri Nov 25 10:35:00 EST 2005 No change in functionality. New version prepared solely to accommodate change in name of String::MkVarName to String::PerlIdentifier. 0.05 Sat Nov 19 12:42:46 EST 2005 File::Save::Home's test suite now uses String::MkVarName v0.03 or later from CPAN, rather than a copy of that module stored under the t/ directory. Appropriate changes to Makefile.PL and t/*.t files made. 0.04 Sun Nov 13 08:46:00 EST 2005 Reworked restore_subhome_directory_status to use code from Perl Cookbook recipe 9.8, rmtree1, to remove directory and its contents. In test files, either eliminated chdir-ing to home directory entirely, or limited its scope to minimum necessary. 0.03 Sat Nov 12 21:38:00 2005 Forgot to include File::Temp under PREREQ_PM in Makefile.PL. 0.02 Sat Nov 12 21:15:00 2005 Reformulated in response to feedback on 0.01 from Michael Graham. First general release version. lib/File/Save/Home.pm exports seven functions on request: get_home_directory get_subhome_directory_status make_subhome_directory restore_subhome_directory_status conceal_target_file reveal_target_file make_subhome_temp_directory There are 4 files in the test suite: 01_test.t 02_multilevel.t 03_placefile.t 04_tempdir.t Underneath the t/ directory there is found package String::MkVarName, which exports one function: make_varname CPAN upload. 0.01 Mon Oct 31 09:55:38 2005 Original version; created by ExtUtils::ModuleMaker 0.43. File-Save-Home-0.12/lib/0000755000175000017500000000000015126332102014446 5ustar jkeenanjkeenanFile-Save-Home-0.12/lib/File/0000755000175000017500000000000015126332102015325 5ustar jkeenanjkeenanFile-Save-Home-0.12/lib/File/Save/0000755000175000017500000000000015126332102016223 5ustar jkeenanjkeenanFile-Save-Home-0.12/lib/File/Save/Home.pm0000644000175000017500000005725215126331701017470 0ustar jkeenanjkeenanpackage File::Save::Home; require 5.006_001; use strict; use warnings; use Exporter (); our $VERSION = '0.12'; our @ISA = qw(Exporter); our @EXPORT_OK = qw( get_home_directory get_subhome_directory_status make_subhome_directory restore_subhome_directory_status conceal_target_file reveal_target_file make_subhome_temp_directory ); our %EXPORT_TAGS = ( subhome_status => [ qw| get_subhome_directory_status restore_subhome_directory_status | ], target => [ qw| conceal_target_file reveal_target_file | ], ); use Carp; use File::Path; use File::Spec::Functions qw| catdir catfile catpath splitdir splitpath |; use File::Temp qw| tempdir |; *ok = *Test::More::ok; use File::Find; #################### DOCUMENTATION ################### =head1 NAME File::Save::Home - Place file safely under user home directory =head1 VERSION This document refers to version 0.12, released January 03 2026. =head1 SYNOPSIS use File::Save::Home qw( get_home_directory get_subhome_directory_status make_subhome_directory restore_subhome_directory_status conceal_target_file reveal_target_file make_subhome_temp_directory ); $home_dir = get_home_directory(); $desired_dir_ref = get_subhome_directory_status("desired/directory"); $desired_dir_ref = get_subhome_directory_status( "desired/directory", "pseudohome/directory", # two-argument version ); $desired_dir = make_subhome_directory($desired_dir_ref); restore_subhome_directory_status($desired_dir_ref); $target_ref = conceal_target_file( { dir => $desired_dir, file => 'file_to_be_checked', test => 0, } ); reveal_target_file($target_ref); $tmpdir = make_subhome_temp_directory(); $tmpdir = make_subhome_temp_directory( "pseudohome/directory", # optional argument version ); =head1 DESCRIPTION In the course of deploying an application on another user's system, you sometimes need to place a file in or underneath that user's home directory. Can you do so safely? This Perl extension provides several functions which try to determine whether you can, indeed, safely create directories and files underneath a user's home directory. Among other things, if you are placing a file in such a location only temporarily -- say, for testing purposes -- you can temporarily hide any already existing file with the same name and restore it to its original name and timestamps when you are done. =head2 Limitations The preceding description was written in 2005. Experience has shown that any claim that one can make about the B of the creation or deletion of directories and files underneath a user's home directory must be qualified. File::Save::Home is satisfactory for the use case for which it was originally designed, but there are other situations where it falls short. The original use case for which File::Save::Home was designed was to support the placement of B in a user's home directory. Such personal preference files are often referred to as B because their names typically start with a C<.> character to render them hidden from commands like C and end in C much like C<.bashrc> or <.shrc>. A developer using CPAN::Mini, for example, often makes use of C<.minicpanrc> to store the developer's preferred CPAN mirror. File::Save::Home was created specifically to support the creation of a C<.modulemakerrc> file by users of ExtUtils::ModuleMaker and a C<.podmultirc> file by users of Pod::Multi. (ExtUtils::ModuleMaker and Pod::Multi are maintained by the author of File::Save::Home.) These libraries are B, I they are intended to assist individual humans in software development rather than being used "in production." As such, their use of dot-rc files implicitly assumes: =over 4 =item * Only one user is concerned with the status of the directories and files, including dot-rc files, underneath the user's home directory. =item * Only one user has permissions to create, modify or remove directories and files underneath the user's home directory -- an assumption that is easily violated by a superuser such as C. =item * The user is running processes to create, modify or remove directories and files underneath the user's home directory B, C the user is B running such processes B. Running such processes in parallel would raise the possibility, for example, of process trying to rename a dot-rc file that a second, parallel process had already deleted. =back When either the second or third assumption above is violated, we have the possibility of B (L) and B