| 1 | package App::FileSync::IO; | ||||||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||||||
| 3 | # Filesystem primitives shared by the client, the server, the trash and the | ||||||||||||||||||||||||||||||||||||||||||||||
| 4 | # snapshots. Each one used to be written out two to four times; keeping them | ||||||||||||||||||||||||||||||||||||||||||||||
| 5 | # here means a fix (such as O_EXCL temporaries) lands everywhere at once. | ||||||||||||||||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||||||||||||||||
| 7 | 341 | ▶ | use App::FileSync::Platform; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||||||||||||||||||||
| 9 | 341 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 10 | 341 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 11 | 341 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||||||||||||||||||||
| 13 | 341 | ▶ | use Digest::SHA (); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 14 | 341 | ▶ | use Exporter qw(import); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 15 | 341 | ▶ | use Fcntl qw(SEEK_END); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 16 | 341 | ▶ | use File::Basename qw(dirname); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 17 | 341 | ▶ | use File::Copy (); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 18 | 341 | ▶ | use File::Path qw(make_path); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 19 | 341 | ▶ | use File::Spec; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 20 | 341 | ▶ | use File::Temp (); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 21 | 341 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 22 | 341 | ▶ | use Sub::Private { mode => 'enforce' }; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 23 | 341 | ▶ | use Time::HiRes (); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||||||||||
| 25 | 341 | ▶ | use App::FileSync::Constants qw($MODE_MASK $TEMP_PREFIX $STAT_MODE $STAT_MTIME $SHA_BITS); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 26 | 341 | ▶ | use App::FileSync::I18N qw(throw os_error strip_location); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||||||||||||||||||||
| 28 | 341 | ▶ | use version; our $VERSION = version->declare('0.002.1'); | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||||||||||||||||||||
| 30 | 341 | our @EXPORT_OK = qw( | |||||||||||||||||||||||||||||||||||||||||||||
| 31 | read_text open_file temp_file write_atomic install_file clear_target | ||||||||||||||||||||||||||||||||||||||||||||||
| 32 | set_mtime sha256_file list_dir copy_preserving append_line ensure_dir | ||||||||||||||||||||||||||||||||||||||||||||||
| 33 | ); | ||||||||||||||||||||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||||||||||||||||||||
| 35 | # File::Temp wants at least four X's; ten keep collisions out of reach even | ||||||||||||||||||||||||||||||||||||||||||||||
| 36 | # with thousands of uploads in one directory. | ||||||||||||||||||||||||||||||||||||||||||||||
| 37 | 341 | Readonly::Scalar my $TEMP_TEMPLATE => $TEMP_PREFIX . ('X' x 10); | |||||||||||||||||||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||||||||||||||||||||
| 39 | # Catalogue key for each open mode, so the error names what was attempted. | ||||||||||||||||||||||||||||||||||||||||||||||
| 40 | 341 | Readonly my %OPEN_KEY => ( | |||||||||||||||||||||||||||||||||||||||||||||
| 41 | '<' => 'io.read', | ||||||||||||||||||||||||||||||||||||||||||||||
| 42 | '>' => 'io.write', | ||||||||||||||||||||||||||||||||||||||||||||||
| 43 | '>>' => 'io.append', | ||||||||||||||||||||||||||||||||||||||||||||||
| 44 | ); | ||||||||||||||||||||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||||||||||||||||||||
| 46 | # The permission bits a new file would get from open() under the current | ||||||||||||||||||||||||||||||||||||||||||||||
| 47 | # umask. File::Temp creates 0600 files, which would otherwise leak into the | ||||||||||||||||||||||||||||||||||||||||||||||
| 48 | # master and every replica. | ||||||||||||||||||||||||||||||||||||||||||||||
| 49 | 341 | Readonly::Scalar my $CREATE_MODE => oct('666'); | |||||||||||||||||||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||||||||||||||||||||
| 51 | # Windows has no POSIX permission bits worth setting. | ||||||||||||||||||||||||||||||||||||||||||||||
| 52 | 341 | Readonly::Scalar my $HAS_MODES => $^O ne 'MSWin32'; | |||||||||||||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||||||||||||||
| 54 | =encoding utf8 | ||||||||||||||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||||||||||||||
| 56 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||||||||||||||||||||
| 58 | App::FileSync::IO - filesystem primitives for App::FileSync | ||||||||||||||||||||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||||||||||||||||||||
| 60 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||||||||||||||||||||||||
| 62 | use App::FileSync::IO qw(write_atomic read_text sha256_file); | ||||||||||||||||||||||||||||||||||||||||||||||
| 63 | |||||||||||||||||||||||||||||||||||||||||||||||
| 64 | write_atomic('/srv/filesync/.filesync/repos/docs/master.json', $json); | ||||||||||||||||||||||||||||||||||||||||||||||
| 65 | my $text = read_text($path); | ||||||||||||||||||||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||||||||||||||||||||
| 67 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||||||||||||||||||||
| 69 | Every function raises a catalogued error (see L<App::FileSync::I18N>) that | ||||||||||||||||||||||||||||||||||||||||||||||
| 70 | names the path and carries the operating system's reason. | ||||||||||||||||||||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||||||||||||||||||||
| 72 | =head1 FUNCTIONS | ||||||||||||||||||||||||||||||||||||||||||||||
| 73 | |||||||||||||||||||||||||||||||||||||||||||||||
| 74 | =head2 open_file | ||||||||||||||||||||||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||||||||||||||||||||
| 76 | Purpose: open a file in binary mode. | ||||||||||||||||||||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||||||||||||||||||||
| 78 | Args: C<$path>, C<$mode> (C<< < >>, C<< > >> or C<<< >> >>>). | ||||||||||||||||||||||||||||||||||||||||||||||
| 79 | |||||||||||||||||||||||||||||||||||||||||||||||
| 80 | Returns: the filehandle. | ||||||||||||||||||||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||||||||||||||||||||
| 82 | Side Effects: creates or truncates the file for C<< > >>, creates it for | ||||||||||||||||||||||||||||||||||||||||||||||
| 83 | C<<< >> >>>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||||||||||||||||||||
| 85 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||||||||||||||||||||
| 87 | my $fh = open_file($path, '<'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||||||||||||||||
| 89 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||||||||||||||||||||
| 91 | my $out = open_file('/tmp/report.bin', '>'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 92 | print {$out} $bytes; | ||||||||||||||||||||||||||||||||||||||||||||||
| 93 | close $out; | ||||||||||||||||||||||||||||||||||||||||||||||
| 94 | |||||||||||||||||||||||||||||||||||||||||||||||
| 95 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||||||||||||||||||||
| 97 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||||||||||||||||||||
| 99 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 100 | { name => 'path', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 101 | { name => 'mode', type => 'string', memberof => [ '<', '>', '>>' ] }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 102 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||||||||||||||||||||
| 104 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||||||||||||||||||||
| 106 | { type => 'handle' } | ||||||||||||||||||||||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||||||||||||||||||||
| 108 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||||||||||||||||||||
| 110 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 111 | io.read the file cannot be opened check it exists and is readable | ||||||||||||||||||||||||||||||||||||||||||||||
| 112 | io.write the file cannot be created check the directory is writable | ||||||||||||||||||||||||||||||||||||||||||||||
| 113 | io.append the file cannot be appended to check permissions and free space | ||||||||||||||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||||||||||||||
| 115 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||||||||||||||||||||
| 117 | open_file : PATH × MODE ↛ HANDLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 118 | pre mode ∈ {<, >, >>} ∧ (mode = < ⇒ path ∈ dom FS) | ||||||||||||||||||||||||||||||||||||||||||||||
| 119 | post mode = > ⇒ FS'(path) = ⟨⟩ | ||||||||||||||||||||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||||||||||||||||||||
| 121 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 122 | |||||||||||||||||||||||||||||||||||||||||||||||
| 123 | 3594 | ▶ | sub open_file { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
open_file: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 124 | 3594 | my ($path, $mode) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 125 | |||||||||||||||||||||||||||||||||||||||||||||||
| 126 | 3594 | my $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 127 | 3594 | ▶ | eval { open $fh, $mode, $path; 1 } | ||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$OPEN_KEY{$mode} || 'io.read'
MC/DC0%0/1
$OPEN_KEY{$mode} || 'io.read'
$OPEN_KEY{$mode}
Truth table50%1/2
A
A= $OPEN_KEY{$mode}
| |||||||||||||||||||||||||||||||||||||||||||||||
| 128 | 3594 | ▶ | or throw($OPEN_KEY{$mode} || 'io.read', { path => $path, error => os_error($@) }); | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 129 | 3591 | binmode $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||||||||||||||
| 131 | 3591 | return $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 132 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||||||||||||||||||||
| 134 | =head2 read_text | ||||||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||||||
| 136 | Purpose: read a whole file as bytes. | ||||||||||||||||||||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||||||||||||||||||||
| 138 | Args: C<$path>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||||||||||||||||||||
| 140 | Returns: the contents (an empty string for an empty file). | ||||||||||||||||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||||||||||||||||
| 142 | Side Effects: none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||||||||||||||||||||
| 144 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||||||||||||||||||||
| 146 | my $json = read_text($config_path); | ||||||||||||||||||||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||||||||||||||||||||
| 148 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||||||||||||||||||||
| 150 | my $marker = read_text("$root/.filesync-root"); | ||||||||||||||||||||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||||||||||||||||||||
| 152 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||||||||||||||||||||||||
| 154 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||||||||||||||||||||
| 156 | [ { name => 'path', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||||||||||||||||||||
| 158 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||||||||||||||||||||
| 160 | { type => 'string' } | ||||||||||||||||||||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||||||||||||||||||||
| 162 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 163 | |||||||||||||||||||||||||||||||||||||||||||||||
| 164 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 165 | io.read the file cannot be opened check it exists and is readable | ||||||||||||||||||||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||||||||||||||||||||
| 167 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||||||||||||||||||||
| 169 | read_text : PATH ↛ seq BYTE | ||||||||||||||||||||||||||||||||||||||||||||||
| 170 | pre path ∈ dom FS | ||||||||||||||||||||||||||||||||||||||||||||||
| 171 | post result = FS(path) | ||||||||||||||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||||||||||||||
| 173 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||||||||||||||
| 175 | 1376 | ▶ | sub read_text { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
read_text: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 176 | 1376 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||||||||||||||||||||
| 178 | 1376 | my $fh = open_file($path, '<'); | |||||||||||||||||||||||||||||||||||||||||||||
| 179 | 1373 | my $text = do { local $/; <$fh> }; | |||||||||||||||||||||||||||||||||||||||||||||
| 180 | 1373 | close $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||||||||||||||||||||
| 182 | 1373 | ▶ | return defined $text ? $text : ''; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 183 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||||||||||||||||||||
| 185 | =head2 temp_file | ||||||||||||||||||||||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||||||||||||||||||||||
| 187 | Purpose: create a temporary file beside its final location. | ||||||||||||||||||||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||||||||||||||||||||
| 189 | Args: C<$directory>; created if missing. | ||||||||||||||||||||||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||||||||||||||||||||||
| 191 | Returns: an arrayref C<[ $filehandle, $path ]>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||||||||||||||||||||
| 193 | Side Effects: creates the file exclusively (C<O_EXCL>), so a planted file or | ||||||||||||||||||||||||||||||||||||||||||||||
| 194 | symlink of the same name cannot be written through. Its permissions are those | ||||||||||||||||||||||||||||||||||||||||||||||
| 195 | an ordinary C<open> would give under the current umask. The name starts with | ||||||||||||||||||||||||||||||||||||||||||||||
| 196 | C<.filesync-tmp->, which the scanner ignores and stale-temp cleanup removes. | ||||||||||||||||||||||||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||||||||||||||||||||||||
| 198 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 199 | |||||||||||||||||||||||||||||||||||||||||||||||
| 200 | my ($fh, $temp) = @{ temp_file($directory) }; | ||||||||||||||||||||||||||||||||||||||||||||||
| 201 | |||||||||||||||||||||||||||||||||||||||||||||||
| 202 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 203 | |||||||||||||||||||||||||||||||||||||||||||||||
| 204 | my ($fh, $temp) = @{ temp_file('/home/foo/Documents/notes') }; | ||||||||||||||||||||||||||||||||||||||||||||||
| 205 | print {$fh} $bytes; | ||||||||||||||||||||||||||||||||||||||||||||||
| 206 | close $fh; | ||||||||||||||||||||||||||||||||||||||||||||||
| 207 | install_file($temp, '/home/foo/Documents/notes/plan.txt'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||||||||||||||||||||
| 209 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||||||||||||||||||||
| 211 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||||||||||||||||||||
| 213 | [ { name => 'directory', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||||||||||||||||||||
| 215 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||||||||||||||||||||
| 217 | { type => 'arrayref', min => 2, max => 2 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||||||||||||||||
| 219 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||||||||||||||||||||
| 221 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 222 | io.mkdir the directory cannot be created check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 223 | io.temp no temporary file can be made there check permissions and free space | ||||||||||||||||||||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||||||||||||||||||||
| 225 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 226 | |||||||||||||||||||||||||||||||||||||||||||||||
| 227 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 228 | dir? : PATH ; t! : PATH | ||||||||||||||||||||||||||||||||||||||||||||||
| 229 | t! ∉ dom FS ∧ dirname(t!) = dir? ∧ FS' = FS ∪ {t! ↦ ⟨⟩} | ||||||||||||||||||||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||||||||||||||||||||
| 231 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 232 | |||||||||||||||||||||||||||||||||||||||||||||||
| 233 | 1043 | ▶ | sub temp_file { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
temp_file: called CC=3 SCAR=11.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 234 | 1043 | my ($directory) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 235 | |||||||||||||||||||||||||||||||||||||||||||||||
| 236 | 1043 | ensure_dir($directory); | |||||||||||||||||||||||||||||||||||||||||||||
| 237 | |||||||||||||||||||||||||||||||||||||||||||||||
| 238 | 1043 | my ($fh, $path); | |||||||||||||||||||||||||||||||||||||||||||||
| 239 | 1043 | ▶ | eval { | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 240 | 1043 | ($fh, $path) = File::Temp::tempfile($TEMP_TEMPLATE, DIR => $directory, UNLINK => 0); | |||||||||||||||||||||||||||||||||||||||||||||
| 241 | 1043 | 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 242 | } or throw('io.temp', { path => $directory, error => os_error($@) }); | ||||||||||||||||||||||||||||||||||||||||||||||
| 243 | |||||||||||||||||||||||||||||||||||||||||||||||
| 244 | 1043 | binmode $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 245 | 1043 | ▶ | chmod($CREATE_MODE & ~umask, $path) if $HAS_MODES; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 246 | |||||||||||||||||||||||||||||||||||||||||||||||
| 247 | 1043 | return [ $fh, $path ]; | |||||||||||||||||||||||||||||||||||||||||||||
| 248 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||||||||||||||||||||
| 250 | =head2 write_atomic | ||||||||||||||||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||||||||||||||||
| 252 | Purpose: replace a file's contents so readers see the old or the new version, | ||||||||||||||||||||||||||||||||||||||||||||||
| 253 | never a mixture. | ||||||||||||||||||||||||||||||||||||||||||||||
| 254 | |||||||||||||||||||||||||||||||||||||||||||||||
| 255 | Args: C<$path>, C<$data> (bytes). | ||||||||||||||||||||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||||||||||||||||||||
| 257 | Returns: 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||||||||||||||||||||
| 259 | Side Effects: creates missing parent directories; writes a temporary file in | ||||||||||||||||||||||||||||||||||||||||||||||
| 260 | the same directory and renames it over C<$path>. The temporary file is | ||||||||||||||||||||||||||||||||||||||||||||||
| 261 | removed if any step fails. | ||||||||||||||||||||||||||||||||||||||||||||||
| 262 | |||||||||||||||||||||||||||||||||||||||||||||||
| 263 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 264 | |||||||||||||||||||||||||||||||||||||||||||||||
| 265 | write_atomic($path, json_encode($config) . "\n"); | ||||||||||||||||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||||||||||||||||
| 267 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||||||||||||||||
| 269 | write_atomic('/tmp/state.json', qq({"ok":1}\n)); | ||||||||||||||||||||||||||||||||||||||||||||||
| 270 | |||||||||||||||||||||||||||||||||||||||||||||||
| 271 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||||||||||||||||||||
| 273 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||||||||||||||||||||
| 275 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 276 | { name => 'path', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 277 | { name => 'data', type => 'string' }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 278 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 279 | |||||||||||||||||||||||||||||||||||||||||||||||
| 280 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 281 | |||||||||||||||||||||||||||||||||||||||||||||||
| 282 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||||||||||||||||||||||
| 284 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||||||||||||||||||||
| 286 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 287 | io.temp no temporary file can be created check permissions and space | ||||||||||||||||||||||||||||||||||||||||||||||
| 288 | io.write writing or closing the file failed check free space | ||||||||||||||||||||||||||||||||||||||||||||||
| 289 | io.rename the new file cannot replace the old check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 290 | |||||||||||||||||||||||||||||||||||||||||||||||
| 291 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 292 | |||||||||||||||||||||||||||||||||||||||||||||||
| 293 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 294 | path? : PATH ; data? : seq BYTE | ||||||||||||||||||||||||||||||||||||||||||||||
| 295 | FS'(path?) = data? | ||||||||||||||||||||||||||||||||||||||||||||||
| 296 | ∀ t : dom FS' \ dom FS • ¬ prefix(TEMP, basename t) | ||||||||||||||||||||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||||||||||||||||||||
| 298 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||||||||||||||||||||
| 300 | 775 | ▶ | sub write_atomic { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
write_atomic: called CC=3 SCAR=11.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 301 | 775 | my ($path, $data) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||||||||||||||||||||
| 303 | 775 | my ($fh, $temp) = @{ temp_file(dirname($path)) }; | |||||||||||||||||||||||||||||||||||||||||||||
| 304 | |||||||||||||||||||||||||||||||||||||||||||||||
| 305 | # print is outside autodie's reach, so its failure is checked here. | ||||||||||||||||||||||||||||||||||||||||||||||
| 306 | 775 | my $written = print {$fh} $data; | |||||||||||||||||||||||||||||||||||||||||||||
| 307 | 775 | my $closed = eval { close $fh; 1 }; | |||||||||||||||||||||||||||||||||||||||||||||
| 308 | 775 | ▶ | unless ($written && $closed) { | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$written and $closed
MC/DC0%0/2
$written and $closed
$written
$closed
Truth table33%1/3
A and B
A= $writtenB= $closed
| |||||||||||||||||||||||||||||||||||||||||||||||
| 309 | 0 | my $error = os_error($@); | |||||||||||||||||||||||||||||||||||||||||||||
| 310 | 0 | _discard($temp); | |||||||||||||||||||||||||||||||||||||||||||||
| 311 | 0 | throw('io.write', { path => $temp, error => $error }); | |||||||||||||||||||||||||||||||||||||||||||||
| 312 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 313 | |||||||||||||||||||||||||||||||||||||||||||||||
| 314 | 775 | _rename_or_discard($temp, $path); | |||||||||||||||||||||||||||||||||||||||||||||
| 315 | 775 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 316 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 317 | |||||||||||||||||||||||||||||||||||||||||||||||
| 318 | =head2 install_file | ||||||||||||||||||||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||||||||||||||||||||
| 320 | Purpose: move a verified temporary file into place. | ||||||||||||||||||||||||||||||||||||||||||||||
| 321 | |||||||||||||||||||||||||||||||||||||||||||||||
| 322 | Args: C<$temp>, C<$target>, optional C<$mtime> (epoch, may be fractional) and | ||||||||||||||||||||||||||||||||||||||||||||||
| 323 | C<$mode> (permission bits). | ||||||||||||||||||||||||||||||||||||||||||||||
| 324 | |||||||||||||||||||||||||||||||||||||||||||||||
| 325 | Returns: C<$target>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||||||||||||||||||||
| 327 | Side Effects: sets the mode (not on Windows) and mtime on C<$temp>, removes | ||||||||||||||||||||||||||||||||||||||||||||||
| 328 | whatever is at C<$target> (a file, a symlink or an empty directory), then | ||||||||||||||||||||||||||||||||||||||||||||||
| 329 | renames. C<$temp> is removed if the rename fails. | ||||||||||||||||||||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||||||||||||||||||||
| 331 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 332 | |||||||||||||||||||||||||||||||||||||||||||||||
| 333 | install_file($temp, $abs, $mtime, $mode); | ||||||||||||||||||||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||||||||||||||||||||
| 335 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 336 | |||||||||||||||||||||||||||||||||||||||||||||||
| 337 | my ($fh, $temp) = @{ temp_file($dir) }; | ||||||||||||||||||||||||||||||||||||||||||||||
| 338 | print {$fh} $content; | ||||||||||||||||||||||||||||||||||||||||||||||
| 339 | close $fh; | ||||||||||||||||||||||||||||||||||||||||||||||
| 340 | install_file($temp, "$dir/report.txt", 1_700_000_000, oct(644)); | ||||||||||||||||||||||||||||||||||||||||||||||
| 341 | |||||||||||||||||||||||||||||||||||||||||||||||
| 342 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||||||||||||||||||||
| 344 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 345 | |||||||||||||||||||||||||||||||||||||||||||||||
| 346 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 347 | { name => 'temp', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 348 | { name => 'target', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 349 | { name => 'mtime', type => 'number', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 350 | { name => 'mode', type => 'integer', optional => 1, min => 0 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 351 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 352 | |||||||||||||||||||||||||||||||||||||||||||||||
| 353 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 354 | |||||||||||||||||||||||||||||||||||||||||||||||
| 355 | { type => 'string', min => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 356 | |||||||||||||||||||||||||||||||||||||||||||||||
| 357 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||||||||||||||||||||
| 359 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 360 | io.remove the old file cannot be removed check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 361 | io.replace_dir a non-empty directory is in the way move it aside | ||||||||||||||||||||||||||||||||||||||||||||||
| 362 | io.rename the new file cannot be moved into place check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 363 | |||||||||||||||||||||||||||||||||||||||||||||||
| 364 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 365 | |||||||||||||||||||||||||||||||||||||||||||||||
| 366 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 367 | temp?, target? : PATH | ||||||||||||||||||||||||||||||||||||||||||||||
| 368 | pre temp? ∈ dom FS | ||||||||||||||||||||||||||||||||||||||||||||||
| 369 | post FS'(target?) = FS(temp?) ∧ temp? ∉ dom FS' | ||||||||||||||||||||||||||||||||||||||||||||||
| 370 | |||||||||||||||||||||||||||||||||||||||||||||||
| 371 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 372 | |||||||||||||||||||||||||||||||||||||||||||||||
| 373 | 265 | ▶ | sub install_file { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
install_file: called CC=3 SCAR=11.6
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 374 | 265 | my ($temp, $target, $mtime, $mode) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 375 | |||||||||||||||||||||||||||||||||||||||||||||||
| 376 | 265 | ▶ | chmod($mode & $MODE_MASK, $temp) if defined $mode && $HAS_MODES; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $mode and $HAS_MODES
MC/DC0%0/2
defined $mode and $HAS_MODES
defined $mode
$HAS_MODES
Truth table33%1/3
A and B
A= defined $modeB= $HAS_MODES
| |||||||||||||||||||||||||||||||||||||||||||||||
| 377 | 265 | set_mtime($temp, $mtime); | |||||||||||||||||||||||||||||||||||||||||||||
| 378 | |||||||||||||||||||||||||||||||||||||||||||||||
| 379 | 265 | clear_target($target); | |||||||||||||||||||||||||||||||||||||||||||||
| 380 | 265 | _rename_or_discard($temp, $target); | |||||||||||||||||||||||||||||||||||||||||||||
| 381 | |||||||||||||||||||||||||||||||||||||||||||||||
| 382 | 265 | return $target; | |||||||||||||||||||||||||||||||||||||||||||||
| 383 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 384 | |||||||||||||||||||||||||||||||||||||||||||||||
| 385 | =head2 clear_target | ||||||||||||||||||||||||||||||||||||||||||||||
| 386 | |||||||||||||||||||||||||||||||||||||||||||||||
| 387 | Purpose: make room for a file at C<$path>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 388 | |||||||||||||||||||||||||||||||||||||||||||||||
| 389 | Args: C<$path>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||||||||||||||||||||
| 391 | Returns: 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||||||||||||||||
| 393 | Side Effects: removes a symlink or file at C<$path>, or an empty directory. | ||||||||||||||||||||||||||||||||||||||||||||||
| 394 | A non-empty directory is never removed. | ||||||||||||||||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||||||||||||||||
| 396 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 397 | |||||||||||||||||||||||||||||||||||||||||||||||
| 398 | clear_target($abs); | ||||||||||||||||||||||||||||||||||||||||||||||
| 399 | |||||||||||||||||||||||||||||||||||||||||||||||
| 400 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 401 | |||||||||||||||||||||||||||||||||||||||||||||||
| 402 | clear_target('/tmp/old-copy.txt'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||||||||||||||||||||
| 404 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 405 | |||||||||||||||||||||||||||||||||||||||||||||||
| 406 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 407 | |||||||||||||||||||||||||||||||||||||||||||||||
| 408 | [ { name => 'path', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 409 | |||||||||||||||||||||||||||||||||||||||||||||||
| 410 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 411 | |||||||||||||||||||||||||||||||||||||||||||||||
| 412 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 413 | |||||||||||||||||||||||||||||||||||||||||||||||
| 414 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 415 | |||||||||||||||||||||||||||||||||||||||||||||||
| 416 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 417 | io.remove the file or symlink cannot go check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 418 | io.replace_dir a non-empty directory is in the way move it aside | ||||||||||||||||||||||||||||||||||||||||||||||
| 419 | |||||||||||||||||||||||||||||||||||||||||||||||
| 420 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||||||||||||||||||||
| 422 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 423 | path? : PATH | ||||||||||||||||||||||||||||||||||||||||||||||
| 424 | path? ∈ dom FS ∧ (kind path? ≠ dir ∨ children path? = ∅) ⇒ path? ∉ dom FS' | ||||||||||||||||||||||||||||||||||||||||||||||
| 425 | |||||||||||||||||||||||||||||||||||||||||||||||
| 426 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 427 | |||||||||||||||||||||||||||||||||||||||||||||||
| 428 | 265 | ▶ | sub clear_target { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
clear_target: called CC=7 SCAR=23.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 429 | 265 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||||||||||||||||||||
| 431 | # Symlinks first: -d follows them, and a link to a directory must be | ||||||||||||||||||||||||||||||||||||||||||||||
| 432 | # unlinked, not rmdir'ed. | ||||||||||||||||||||||||||||||||||||||||||||||
| 433 | 265 | ▶ | if (-l $path || (-e _ && !-d _)) { | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
Condition66%4/6
-l $path or -e _ and not -d _
-e _ and not -d _
MC/DC33%1/3
-l $path or -e _ and not -d _
-l $path
-e _
not -d _
Truth table50%2/4
A or B and not(C)
A= -l $pathB= -e _C= not -d _
| |||||||||||||||||||||||||||||||||||||||||||||||
| 434 | 13 | ▶ | eval { unlink $path; 1 } or throw('io.remove', { path => $path, error => os_error($@) }); | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 435 | } elsif (-d _) { | ||||||||||||||||||||||||||||||||||||||||||||||
| 436 | 0 | ▶ | eval { rmdir $path; 1 } or throw('io.replace_dir', { path => $path }); | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 437 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 438 | |||||||||||||||||||||||||||||||||||||||||||||||
| 439 | 265 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 440 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 441 | |||||||||||||||||||||||||||||||||||||||||||||||
| 442 | =head2 set_mtime | ||||||||||||||||||||||||||||||||||||||||||||||
| 443 | |||||||||||||||||||||||||||||||||||||||||||||||
| 444 | Purpose: set a file's modification time, keeping sub-second precision where | ||||||||||||||||||||||||||||||||||||||||||||||
| 445 | the platform allows. | ||||||||||||||||||||||||||||||||||||||||||||||
| 446 | |||||||||||||||||||||||||||||||||||||||||||||||
| 447 | Args: C<$path>, C<$mtime> (epoch; C<undef> leaves the file alone). | ||||||||||||||||||||||||||||||||||||||||||||||
| 448 | |||||||||||||||||||||||||||||||||||||||||||||||
| 449 | Returns: 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 450 | |||||||||||||||||||||||||||||||||||||||||||||||
| 451 | Side Effects: changes the file's atime and mtime. Where C<Time::HiRes::utime> | ||||||||||||||||||||||||||||||||||||||||||||||
| 452 | is unimplemented (some Windows builds) whole seconds are stored, which the | ||||||||||||||||||||||||||||||||||||||||||||||
| 453 | 2-second comparison tolerance already allows for. | ||||||||||||||||||||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||||||||||||||||||||
| 455 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 456 | |||||||||||||||||||||||||||||||||||||||||||||||
| 457 | set_mtime($temp, 1_700_000_123.456); | ||||||||||||||||||||||||||||||||||||||||||||||
| 458 | |||||||||||||||||||||||||||||||||||||||||||||||
| 459 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 460 | |||||||||||||||||||||||||||||||||||||||||||||||
| 461 | set_mtime('/tmp/a.txt', time - 3600); | ||||||||||||||||||||||||||||||||||||||||||||||
| 462 | |||||||||||||||||||||||||||||||||||||||||||||||
| 463 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 464 | |||||||||||||||||||||||||||||||||||||||||||||||
| 465 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 466 | |||||||||||||||||||||||||||||||||||||||||||||||
| 467 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 468 | { name => 'path', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 469 | { name => 'mtime', type => 'number', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 470 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 471 | |||||||||||||||||||||||||||||||||||||||||||||||
| 472 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||||||||||||||||
| 474 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 475 | |||||||||||||||||||||||||||||||||||||||||||||||
| 476 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 477 | |||||||||||||||||||||||||||||||||||||||||||||||
| 478 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 479 | io.utime the timestamp cannot be set check ownership of the file | ||||||||||||||||||||||||||||||||||||||||||||||
| 480 | |||||||||||||||||||||||||||||||||||||||||||||||
| 481 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 482 | |||||||||||||||||||||||||||||||||||||||||||||||
| 483 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 484 | path? : PATH ; m? : ℝ ∪ {⊥} | ||||||||||||||||||||||||||||||||||||||||||||||
| 485 | m? = ⊥ ⇒ FS' = FS | ||||||||||||||||||||||||||||||||||||||||||||||
| 486 | m? ≠ ⊥ ⇒ |mtime'(path?) − m?| < 1 | ||||||||||||||||||||||||||||||||||||||||||||||
| 487 | |||||||||||||||||||||||||||||||||||||||||||||||
| 488 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 489 | |||||||||||||||||||||||||||||||||||||||||||||||
| 490 | 268 | ▶ | sub set_mtime { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
set_mtime: called CC=6 SCAR=18.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 491 | 268 | my ($path, $mtime) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 492 | |||||||||||||||||||||||||||||||||||||||||||||||
| 493 | 268 | ▶ | return 1 if !defined $mtime || eval { Time::HiRes::utime($mtime, $mtime, $path); 1 }; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
not defined $mtime or eval {
do {
&Time::HiRes::utime($mtime, $mtime, $path);
1
}
}
MC/DC50%1/2
not defined $mtime or eval {
do {
&Time::HiRes::utime($mtime, $mtime, $path);
1
}
}
not defined $mtime
eval {
do {
&Time::HiRes::utime($mtime, $mtime, $path);
1
}
}
Truth table66%2/3
not(A) or B
A= not defined $mtimeB= eval {
do {
&Time::HiRes::utime($mtime, $mtime, $path);
1
}
}
| |||||||||||||||||||||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||||||||||||||||||||
| 495 | # Only the "unimplemented" croak is expected; anything else is a real | ||||||||||||||||||||||||||||||||||||||||||||||
| 496 | # failure, reported with the reason Time::HiRes gave. | ||||||||||||||||||||||||||||||||||||||||||||||
| 497 | 2 | my $error = $@; | |||||||||||||||||||||||||||||||||||||||||||||
| 498 | 2 | ▶ | throw('io.utime', { path => $path, error => strip_location($error) }) | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
not ref $error and $error =~ /unimplemented/i
MC/DC50%1/2
not ref $error and $error =~ /unimplemented/i
not ref $error
$error =~ /unimplemented/i
Truth table66%2/3
not(A) and B
A= not ref $errorB= $error =~ /unimplemented/i
| |||||||||||||||||||||||||||||||||||||||||||||||
| 499 | unless !ref $error && $error =~ /unimplemented/i; | ||||||||||||||||||||||||||||||||||||||||||||||
| 500 | |||||||||||||||||||||||||||||||||||||||||||||||
| 501 | 1 | ▶ | eval { utime(int($mtime), int($mtime), $path); 1 } | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 502 | or throw('io.utime', { path => $path, error => os_error($@) }); | ||||||||||||||||||||||||||||||||||||||||||||||
| 503 | 1 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 504 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||||||||||||||||||||
| 506 | =head2 sha256_file | ||||||||||||||||||||||||||||||||||||||||||||||
| 507 | |||||||||||||||||||||||||||||||||||||||||||||||
| 508 | Purpose: hash a file's contents. | ||||||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||||||
| 510 | Args: C<$path>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||||||||||||||||||||
| 512 | Returns: the lower-case hex SHA-256, or C<undef> when C<$path> is not a | ||||||||||||||||||||||||||||||||||||||||||||||
| 513 | readable regular file. | ||||||||||||||||||||||||||||||||||||||||||||||
| 514 | |||||||||||||||||||||||||||||||||||||||||||||||
| 515 | Side Effects: none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 516 | |||||||||||||||||||||||||||||||||||||||||||||||
| 517 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 518 | |||||||||||||||||||||||||||||||||||||||||||||||
| 519 | my $hash = sha256_file($abs); | ||||||||||||||||||||||||||||||||||||||||||||||
| 520 | |||||||||||||||||||||||||||||||||||||||||||||||
| 521 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 522 | |||||||||||||||||||||||||||||||||||||||||||||||
| 523 | print sha256_file('/etc/hostname'), "\n"; | ||||||||||||||||||||||||||||||||||||||||||||||
| 524 | |||||||||||||||||||||||||||||||||||||||||||||||
| 525 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 526 | |||||||||||||||||||||||||||||||||||||||||||||||
| 527 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 528 | |||||||||||||||||||||||||||||||||||||||||||||||
| 529 | [ { name => 'path', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 530 | |||||||||||||||||||||||||||||||||||||||||||||||
| 531 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 532 | |||||||||||||||||||||||||||||||||||||||||||||||
| 533 | { type => 'string', optional => 1, matches => qr/\A[0-9a-f]{64}\z/ } | ||||||||||||||||||||||||||||||||||||||||||||||
| 534 | |||||||||||||||||||||||||||||||||||||||||||||||
| 535 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 536 | |||||||||||||||||||||||||||||||||||||||||||||||
| 537 | None; an unreadable file yields C<undef>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 538 | |||||||||||||||||||||||||||||||||||||||||||||||
| 539 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 540 | |||||||||||||||||||||||||||||||||||||||||||||||
| 541 | sha256_file : PATH ⇸ HEX64 | ||||||||||||||||||||||||||||||||||||||||||||||
| 542 | sha256_file(p) = sha256(FS(p)) if p ∈ dom FS ∧ kind p = file ∧ readable p | ||||||||||||||||||||||||||||||||||||||||||||||
| 543 | |||||||||||||||||||||||||||||||||||||||||||||||
| 544 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 545 | |||||||||||||||||||||||||||||||||||||||||||||||
| 546 | 8 | ▶ | sub sha256_file { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
sha256_file: called CC=3 SCAR=11.6
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 547 | 8 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 548 | |||||||||||||||||||||||||||||||||||||||||||||||
| 549 | 8 | my $sha = Digest::SHA->new($SHA_BITS); | |||||||||||||||||||||||||||||||||||||||||||||
| 550 | 8 | ▶ | my $ok = -f $path && eval { $sha->addfile($path, 'b'); 1 }; | ||||||||||||||||||||||||||||||||||||||||||||
|
Condition33%1/3
-f $path && eval {
do {
$sha->addfile($path, 'b');
1
}
}
MC/DC0%0/2
-f $path && eval {
do {
$sha->addfile($path, 'b');
1
}
}
-f $path
eval {
do {
$sha->addfile($path, 'b');
1
}
}
Truth table33%1/3
A && B
A= -f $pathB= eval {
do {
$sha->addfile($path, 'b');
1
}
}
| |||||||||||||||||||||||||||||||||||||||||||||||
| 551 | |||||||||||||||||||||||||||||||||||||||||||||||
| 552 | 8 | ▶ | return $ok ? $sha->hexdigest() : undef; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 553 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||||||||||||||||||||
| 555 | =head2 list_dir | ||||||||||||||||||||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||||||||||||||||||||
| 557 | Purpose: the entries of a directory. | ||||||||||||||||||||||||||||||||||||||||||||||
| 558 | |||||||||||||||||||||||||||||||||||||||||||||||
| 559 | Args: C<$directory>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 560 | |||||||||||||||||||||||||||||||||||||||||||||||
| 561 | Returns: an arrayref of names, sorted, without C<.> and C<..>; C<undef> when | ||||||||||||||||||||||||||||||||||||||||||||||
| 562 | the directory cannot be read (C<$!> says why). | ||||||||||||||||||||||||||||||||||||||||||||||
| 563 | |||||||||||||||||||||||||||||||||||||||||||||||
| 564 | Side Effects: none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 565 | |||||||||||||||||||||||||||||||||||||||||||||||
| 566 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 567 | |||||||||||||||||||||||||||||||||||||||||||||||
| 568 | my $names = list_dir($dir) or return 0; | ||||||||||||||||||||||||||||||||||||||||||||||
| 569 | |||||||||||||||||||||||||||||||||||||||||||||||
| 570 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 571 | |||||||||||||||||||||||||||||||||||||||||||||||
| 572 | print "$_\n" for @{ list_dir('/tmp') || [] }; | ||||||||||||||||||||||||||||||||||||||||||||||
| 573 | |||||||||||||||||||||||||||||||||||||||||||||||
| 574 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||||||||||||||||
| 576 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 577 | |||||||||||||||||||||||||||||||||||||||||||||||
| 578 | [ { name => 'directory', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 579 | |||||||||||||||||||||||||||||||||||||||||||||||
| 580 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 581 | |||||||||||||||||||||||||||||||||||||||||||||||
| 582 | { type => 'arrayref', optional => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 583 | |||||||||||||||||||||||||||||||||||||||||||||||
| 584 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 585 | |||||||||||||||||||||||||||||||||||||||||||||||
| 586 | None; an unreadable directory yields C<undef>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 587 | |||||||||||||||||||||||||||||||||||||||||||||||
| 588 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 589 | |||||||||||||||||||||||||||||||||||||||||||||||
| 590 | list_dir : PATH ⇸ seq NAME | ||||||||||||||||||||||||||||||||||||||||||||||
| 591 | list_dir(d) = sort(children d \ {".", ".."}) if readable d | ||||||||||||||||||||||||||||||||||||||||||||||
| 592 | |||||||||||||||||||||||||||||||||||||||||||||||
| 593 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 594 | |||||||||||||||||||||||||||||||||||||||||||||||
| 595 | 1507 | ▶ | sub list_dir { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
list_dir: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 596 | 1507 | my ($directory) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 597 | |||||||||||||||||||||||||||||||||||||||||||||||
| 598 | # A missing or unreadable directory is an answer here, not an exception, | ||||||||||||||||||||||||||||||||||||||||||||||
| 599 | # so autodie is switched off for this one call and $! is left for the | ||||||||||||||||||||||||||||||||||||||||||||||
| 600 | # caller to report. | ||||||||||||||||||||||||||||||||||||||||||||||
| 601 | 1507 | my $dh; | |||||||||||||||||||||||||||||||||||||||||||||
| 602 | 341 | ▶ | my $opened = do { no autodie qw(opendir); opendir($dh, $directory) }; | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 603 | 1507 | ▶ | return undef unless $opened; ## no critic (Subroutines::ProhibitExplicitReturnUndef) | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||||||||||||||||||||
| 605 | 1506 | ▶ | my @names = sort grep { $_ ne '.' && $_ ne '..' } readdir($dh); | ||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
$_ ne '.' && $_ ne '..'
MC/DC100%2/2
$_ ne '.' && $_ ne '..'
$_ ne '.'
$_ ne '..'
Truth table100%3/3
A && B
A= $_ ne '.'B= $_ ne '..'
| |||||||||||||||||||||||||||||||||||||||||||||||
| 606 | 1506 | closedir $dh; | |||||||||||||||||||||||||||||||||||||||||||||
| 607 | |||||||||||||||||||||||||||||||||||||||||||||||
| 608 | 1506 | return \@names; | |||||||||||||||||||||||||||||||||||||||||||||
| 609 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 610 | |||||||||||||||||||||||||||||||||||||||||||||||
| 611 | =head2 copy_preserving | ||||||||||||||||||||||||||||||||||||||||||||||
| 612 | |||||||||||||||||||||||||||||||||||||||||||||||
| 613 | Purpose: copy one regular file, keeping its mode and mtime. | ||||||||||||||||||||||||||||||||||||||||||||||
| 614 | |||||||||||||||||||||||||||||||||||||||||||||||
| 615 | Args: C<$source>, C<$destination>, optional C<\@stat> of the source (saves a | ||||||||||||||||||||||||||||||||||||||||||||||
| 616 | second C<stat> when the caller already has one). | ||||||||||||||||||||||||||||||||||||||||||||||
| 617 | |||||||||||||||||||||||||||||||||||||||||||||||
| 618 | Returns: 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 619 | |||||||||||||||||||||||||||||||||||||||||||||||
| 620 | Side Effects: creates C<$destination>'s parent directories; overwrites | ||||||||||||||||||||||||||||||||||||||||||||||
| 621 | C<$destination>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 622 | |||||||||||||||||||||||||||||||||||||||||||||||
| 623 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 624 | |||||||||||||||||||||||||||||||||||||||||||||||
| 625 | copy_preserving($from, $to, \@stat); | ||||||||||||||||||||||||||||||||||||||||||||||
| 626 | |||||||||||||||||||||||||||||||||||||||||||||||
| 627 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 628 | |||||||||||||||||||||||||||||||||||||||||||||||
| 629 | copy_preserving('/srv/a.txt', '/backup/a.txt'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 630 | |||||||||||||||||||||||||||||||||||||||||||||||
| 631 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 632 | |||||||||||||||||||||||||||||||||||||||||||||||
| 633 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 634 | |||||||||||||||||||||||||||||||||||||||||||||||
| 635 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 636 | { name => 'source', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 637 | { name => 'destination', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 638 | { name => 'stat', type => 'arrayref', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 639 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||||||||||||||||||||
| 641 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 642 | |||||||||||||||||||||||||||||||||||||||||||||||
| 643 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 644 | |||||||||||||||||||||||||||||||||||||||||||||||
| 645 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 646 | |||||||||||||||||||||||||||||||||||||||||||||||
| 647 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 648 | io.copy the copy could not be made check space and permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 649 | |||||||||||||||||||||||||||||||||||||||||||||||
| 650 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 651 | |||||||||||||||||||||||||||||||||||||||||||||||
| 652 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 653 | src?, dst? : PATH | ||||||||||||||||||||||||||||||||||||||||||||||
| 654 | FS'(dst?) = FS(src?) ∧ mtime'(dst?) = mtime(src?) ∧ mode'(dst?) = mode(src?) | ||||||||||||||||||||||||||||||||||||||||||||||
| 655 | |||||||||||||||||||||||||||||||||||||||||||||||
| 656 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 657 | |||||||||||||||||||||||||||||||||||||||||||||||
| 658 | 16 | ▶ | sub copy_preserving { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
copy_preserving: called CC=5 SCAR=17.3
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 659 | 16 | my ($source, $destination, $stat) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 660 | |||||||||||||||||||||||||||||||||||||||||||||||
| 661 | 16 | ▶ | $stat = [ Time::HiRes::stat($source) ] unless ref($stat) eq 'ARRAY' && @{$stat}; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
ref $stat eq "ARRAY" and @{$stat;}
MC/DC0%0/2
ref $stat eq "ARRAY" and @{$stat;}
ref $stat eq "ARRAY"
@{$stat;}
Truth table33%1/3
A and B
A= ref $stat eq "ARRAY"B= @{$stat;}
| |||||||||||||||||||||||||||||||||||||||||||||||
| 662 | 16 | ensure_dir(dirname($destination)); | |||||||||||||||||||||||||||||||||||||||||||||
| 663 | |||||||||||||||||||||||||||||||||||||||||||||||
| 664 | 16 | ▶ | File::Copy::copy($source, $destination) | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 665 | or throw('io.copy', { from => $source, to => $destination, error => "$!" }); | ||||||||||||||||||||||||||||||||||||||||||||||
| 666 | |||||||||||||||||||||||||||||||||||||||||||||||
| 667 | 16 | ▶ | chmod($stat->[$STAT_MODE] & $MODE_MASK, $destination) if $HAS_MODES; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 668 | 16 | utime($stat->[$STAT_MTIME], $stat->[$STAT_MTIME], $destination); | |||||||||||||||||||||||||||||||||||||||||||||
| 669 | |||||||||||||||||||||||||||||||||||||||||||||||
| 670 | 16 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 671 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 672 | |||||||||||||||||||||||||||||||||||||||||||||||
| 673 | =head2 append_line | ||||||||||||||||||||||||||||||||||||||||||||||
| 674 | |||||||||||||||||||||||||||||||||||||||||||||||
| 675 | Purpose: append one line to a log or journal. | ||||||||||||||||||||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||||||||||||||||||||
| 677 | Args: C<$path>, C<$line> (without a newline). | ||||||||||||||||||||||||||||||||||||||||||||||
| 678 | |||||||||||||||||||||||||||||||||||||||||||||||
| 679 | Returns: 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 680 | |||||||||||||||||||||||||||||||||||||||||||||||
| 681 | Side Effects: creates C<$path> and its directory if needed. If the file ends | ||||||||||||||||||||||||||||||||||||||||||||||
| 682 | in a torn line from a killed run, a newline is written first so the new entry | ||||||||||||||||||||||||||||||||||||||||||||||
| 683 | is not glued to the fragment. | ||||||||||||||||||||||||||||||||||||||||||||||
| 684 | |||||||||||||||||||||||||||||||||||||||||||||||
| 685 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 686 | |||||||||||||||||||||||||||||||||||||||||||||||
| 687 | append_line($journal, json_encode($event)); | ||||||||||||||||||||||||||||||||||||||||||||||
| 688 | |||||||||||||||||||||||||||||||||||||||||||||||
| 689 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 690 | |||||||||||||||||||||||||||||||||||||||||||||||
| 691 | append_line('/tmp/run.log', 'started'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 692 | |||||||||||||||||||||||||||||||||||||||||||||||
| 693 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 694 | |||||||||||||||||||||||||||||||||||||||||||||||
| 695 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 696 | |||||||||||||||||||||||||||||||||||||||||||||||
| 697 | [ | ||||||||||||||||||||||||||||||||||||||||||||||
| 698 | { name => 'path', type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 699 | { name => 'line', type => 'string' }, | ||||||||||||||||||||||||||||||||||||||||||||||
| 700 | ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 701 | |||||||||||||||||||||||||||||||||||||||||||||||
| 702 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||||||||||||||||||||
| 704 | { type => 'integer', min => 1, max => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 705 | |||||||||||||||||||||||||||||||||||||||||||||||
| 706 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 707 | |||||||||||||||||||||||||||||||||||||||||||||||
| 708 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 709 | io.append the file cannot be appended to check permissions and space | ||||||||||||||||||||||||||||||||||||||||||||||
| 710 | |||||||||||||||||||||||||||||||||||||||||||||||
| 711 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 712 | |||||||||||||||||||||||||||||||||||||||||||||||
| 713 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 714 | path? : PATH ; line? : seq CHAR | ||||||||||||||||||||||||||||||||||||||||||||||
| 715 | let old = FS(path?) if path? ∈ dom FS, else ⟨⟩ | ||||||||||||||||||||||||||||||||||||||||||||||
| 716 | let sep = "\n" if old ≠ ⟨⟩ ∧ last old ≠ "\n", else ⟨⟩ | ||||||||||||||||||||||||||||||||||||||||||||||
| 717 | FS'(path?) = old ⁀ sep ⁀ line? ⁀ "\n" | ||||||||||||||||||||||||||||||||||||||||||||||
| 718 | |||||||||||||||||||||||||||||||||||||||||||||||
| 719 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 720 | |||||||||||||||||||||||||||||||||||||||||||||||
| 721 | 731 | ▶ | sub append_line { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
append_line: called CC=4 SCAR=14.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 722 | 731 | my ($path, $line) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 723 | |||||||||||||||||||||||||||||||||||||||||||||||
| 724 | 731 | ensure_dir(dirname($path)); | |||||||||||||||||||||||||||||||||||||||||||||
| 725 | 731 | ▶ | my $prefix = _ends_mid_line($path) ? "\n" : ''; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 726 | |||||||||||||||||||||||||||||||||||||||||||||||
| 727 | 731 | my $fh = open_file($path, '>>'); | |||||||||||||||||||||||||||||||||||||||||||||
| 728 | 731 | my $written = print {$fh} $prefix, $line, "\n"; | |||||||||||||||||||||||||||||||||||||||||||||
| 729 | 731 | my $closed = eval { close $fh; 1 }; | |||||||||||||||||||||||||||||||||||||||||||||
| 730 | 731 | ▶ | throw('io.append', { path => $path, error => os_error($@) }) unless $written && $closed; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$written and $closed
MC/DC0%0/2
$written and $closed
$written
$closed
Truth table33%1/3
A and B
A= $writtenB= $closed
| |||||||||||||||||||||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||||||||||||||||||||
| 732 | 731 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 733 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 734 | |||||||||||||||||||||||||||||||||||||||||||||||
| 735 | =head2 ensure_dir | ||||||||||||||||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||||||||||||||||
| 737 | Purpose: make sure a directory exists. | ||||||||||||||||||||||||||||||||||||||||||||||
| 738 | |||||||||||||||||||||||||||||||||||||||||||||||
| 739 | Args: C<$directory>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 740 | |||||||||||||||||||||||||||||||||||||||||||||||
| 741 | Returns: C<$directory>. | ||||||||||||||||||||||||||||||||||||||||||||||
| 742 | |||||||||||||||||||||||||||||||||||||||||||||||
| 743 | Side Effects: creates it and any missing parents. | ||||||||||||||||||||||||||||||||||||||||||||||
| 744 | |||||||||||||||||||||||||||||||||||||||||||||||
| 745 | Usage: | ||||||||||||||||||||||||||||||||||||||||||||||
| 746 | |||||||||||||||||||||||||||||||||||||||||||||||
| 747 | ensure_dir(dirname($path)); | ||||||||||||||||||||||||||||||||||||||||||||||
| 748 | |||||||||||||||||||||||||||||||||||||||||||||||
| 749 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||
| 750 | |||||||||||||||||||||||||||||||||||||||||||||||
| 751 | ensure_dir('/tmp/a/b/c'); | ||||||||||||||||||||||||||||||||||||||||||||||
| 752 | |||||||||||||||||||||||||||||||||||||||||||||||
| 753 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 754 | |||||||||||||||||||||||||||||||||||||||||||||||
| 755 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||||||||||||||||||||
| 757 | [ { name => 'directory', type => 'string', min => 1 } ] | ||||||||||||||||||||||||||||||||||||||||||||||
| 758 | |||||||||||||||||||||||||||||||||||||||||||||||
| 759 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||
| 760 | |||||||||||||||||||||||||||||||||||||||||||||||
| 761 | { type => 'string', min => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||
| 762 | |||||||||||||||||||||||||||||||||||||||||||||||
| 763 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||
| 764 | |||||||||||||||||||||||||||||||||||||||||||||||
| 765 | Key Meaning Resolution | ||||||||||||||||||||||||||||||||||||||||||||||
| 766 | io.mkdir the directory cannot be created check permissions | ||||||||||||||||||||||||||||||||||||||||||||||
| 767 | |||||||||||||||||||||||||||||||||||||||||||||||
| 768 | =head3 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||
| 769 | |||||||||||||||||||||||||||||||||||||||||||||||
| 770 | ΔFS | ||||||||||||||||||||||||||||||||||||||||||||||
| 771 | d? : PATH | ||||||||||||||||||||||||||||||||||||||||||||||
| 772 | kind'(d?) = dir ∧ ∀ a : ancestors d? • kind'(a) = dir | ||||||||||||||||||||||||||||||||||||||||||||||
| 773 | |||||||||||||||||||||||||||||||||||||||||||||||
| 774 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||
| 775 | |||||||||||||||||||||||||||||||||||||||||||||||
| 776 | 3142 | ▶ | sub ensure_dir { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
ensure_dir: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||
| 777 | 3142 | my ($directory) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 778 | |||||||||||||||||||||||||||||||||||||||||||||||
| 779 | 3142 | ▶ | unless (-d $directory) { | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 780 | 676 | make_path($directory, { error => \my $errors }); | |||||||||||||||||||||||||||||||||||||||||||||
| 781 | 676 | ▶ | throw('io.mkdir', { path => $directory, error => _path_error($errors) }) | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 782 | unless -d $directory; | ||||||||||||||||||||||||||||||||||||||||||||||
| 783 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 784 | |||||||||||||||||||||||||||||||||||||||||||||||
| 785 | 3140 | return $directory; | |||||||||||||||||||||||||||||||||||||||||||||
| 786 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 787 | |||||||||||||||||||||||||||||||||||||||||||||||
| 788 | # _rename_or_discard | ||||||||||||||||||||||||||||||||||||||||||||||
| 789 | # Purpose: rename a temporary file over its target. | ||||||||||||||||||||||||||||||||||||||||||||||
| 790 | # Entry: $temp exists; $target's directory exists. | ||||||||||||||||||||||||||||||||||||||||||||||
| 791 | # Exit: returns 1, or raises io.rename after removing $temp. | ||||||||||||||||||||||||||||||||||||||||||||||
| 792 | # Side effects: $temp disappears either way. | ||||||||||||||||||||||||||||||||||||||||||||||
| 793 | 1040 | ▶ | sub _rename_or_discard :Private { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_rename_or_discard: called CC=2 SCAR=8.1
| |||||||||||||||||||||||||||||||||||||||||||||||
| 794 | 1040 | my ($temp, $target) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 795 | |||||||||||||||||||||||||||||||||||||||||||||||
| 796 | 1040 | ▶ | unless (eval { rename $temp, $target; 1 }) { | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 797 | 0 | my $error = os_error($@); | |||||||||||||||||||||||||||||||||||||||||||||
| 798 | 0 | _discard($temp); | |||||||||||||||||||||||||||||||||||||||||||||
| 799 | 0 | throw('io.rename', { from => $temp, to => $target, error => $error }); | |||||||||||||||||||||||||||||||||||||||||||||
| 800 | } | ||||||||||||||||||||||||||||||||||||||||||||||
| 801 | |||||||||||||||||||||||||||||||||||||||||||||||
| 802 | 1040 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 803 | 341 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 804 | |||||||||||||||||||||||||||||||||||||||||||||||
| 805 | # _discard | ||||||||||||||||||||||||||||||||||||||||||||||
| 806 | # Purpose: best-effort removal of a temporary file after a failure. | ||||||||||||||||||||||||||||||||||||||||||||||
| 807 | # Entry: $path may or may not exist. | ||||||||||||||||||||||||||||||||||||||||||||||
| 808 | # Exit: returns 1. | ||||||||||||||||||||||||||||||||||||||||||||||
| 809 | # Side effects: removes $path when it can; never raises, so the original | ||||||||||||||||||||||||||||||||||||||||||||||
| 810 | # error is the one the caller reports. | ||||||||||||||||||||||||||||||||||||||||||||||
| 811 | 0 | ▶ | sub _discard :Private { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_discard: not called CC=1 SCAR=1.7
| |||||||||||||||||||||||||||||||||||||||||||||||
| 812 | 0 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 813 | |||||||||||||||||||||||||||||||||||||||||||||||
| 814 | 0 | ▶ | { no autodie qw(unlink); unlink $path } | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.6
| |||||||||||||||||||||||||||||||||||||||||||||||
| 815 | 0 | return 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 816 | 341 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 817 | |||||||||||||||||||||||||||||||||||||||||||||||
| 818 | # _ends_mid_line | ||||||||||||||||||||||||||||||||||||||||||||||
| 819 | # Purpose: detect a log or journal whose last line was torn by a kill. | ||||||||||||||||||||||||||||||||||||||||||||||
| 820 | # Entry: $path may or may not exist. | ||||||||||||||||||||||||||||||||||||||||||||||
| 821 | # Exit: returns 1 when the file is non-empty and its last byte is not | ||||||||||||||||||||||||||||||||||||||||||||||
| 822 | # a newline, otherwise 0. | ||||||||||||||||||||||||||||||||||||||||||||||
| 823 | # Side effects: none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 824 | 731 | ▶ | sub _ends_mid_line :Private { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_ends_mid_line: called CC=4 SCAR=13.9
| |||||||||||||||||||||||||||||||||||||||||||||||
| 825 | 731 | my ($path) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 826 | |||||||||||||||||||||||||||||||||||||||||||||||
| 827 | 731 | ▶ | return 0 unless -s $path; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 828 | |||||||||||||||||||||||||||||||||||||||||||||||
| 829 | 594 | my $fh = open_file($path, '<'); | |||||||||||||||||||||||||||||||||||||||||||||
| 830 | # Only the final byte matters. | ||||||||||||||||||||||||||||||||||||||||||||||
| 831 | 594 | seek($fh, -1, SEEK_END); | |||||||||||||||||||||||||||||||||||||||||||||
| 832 | 594 | read($fh, my $last, 1); | |||||||||||||||||||||||||||||||||||||||||||||
| 833 | 594 | close $fh; | |||||||||||||||||||||||||||||||||||||||||||||
| 834 | |||||||||||||||||||||||||||||||||||||||||||||||
| 835 | 594 | ▶ | return (defined $last && $last ne "\n") ? 1 : 0; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $last and $last ne "\n"
MC/DC50%1/2
defined $last and $last ne "\n"
defined $last
$last ne "\n"
Truth table66%2/3
A and B
A= defined $lastB= $last ne "\n"
| |||||||||||||||||||||||||||||||||||||||||||||||
| 836 | 341 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 837 | |||||||||||||||||||||||||||||||||||||||||||||||
| 838 | # _path_error | ||||||||||||||||||||||||||||||||||||||||||||||
| 839 | # Purpose: the first reason File::Path recorded, for an io.mkdir message. | ||||||||||||||||||||||||||||||||||||||||||||||
| 840 | # Entry: $errors is File::Path's error arrayref (may be undef or empty). | ||||||||||||||||||||||||||||||||||||||||||||||
| 841 | # Exit: returns the reason text, or the current $! when there is none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 842 | # Side effects: none. | ||||||||||||||||||||||||||||||||||||||||||||||
| 843 | 2 | ▶ | sub _path_error :Private { | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_path_error: called CC=5 SCAR=17.8
| |||||||||||||||||||||||||||||||||||||||||||||||
| 844 | 2 | my ($errors) = @_; | |||||||||||||||||||||||||||||||||||||||||||||
| 845 | |||||||||||||||||||||||||||||||||||||||||||||||
| 846 | 2 | ▶ | my ($first) = @{ $errors || [] }; | ||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$errors || []
MC/DC0%0/1
$errors || []
$errors
Truth table50%1/2
A
A= $errors
| |||||||||||||||||||||||||||||||||||||||||||||||
| 847 | 2 | ▶ | my ($reason) = $first ? values %{$first} : (); | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||
| 848 | 2 | ▶ | return defined $reason && length $reason ? $reason : "$!"; | ||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $reason and length $reason
MC/DC0%0/2
defined $reason and length $reason
defined $reason
length $reason
Truth table33%1/3
A and B
A= defined $reasonB= length $reason
| |||||||||||||||||||||||||||||||||||||||||||||||
| 849 | 341 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||||||||||||||||||||
| 851 | 341 | 1; | |||||||||||||||||||||||||||||||||||||||||||||
| 852 | |||||||||||||||||||||||||||||||||||||||||||||||
| 853 | __END__ | ||||||||||||||||||||||||||||||||||||||||||||||