File Coverage

blib/lib/Filesys/POSIX/Snapshot.pm
Criterion Covered Total %
statement 28 28 100.0
branch 4 4 100.0
condition n/a
subroutine 8 8 100.0
pod 2 2 100.0
total 42 42 100.0


line stmt bran cond sub pod time code
1             # Copyright (c) 2014, cPanel, Inc.
2             # All rights reserved.
3             # http://cpanel.net/
4             #
5             # This is free software; you can redistribute it and/or modify it under the same
6             # terms as Perl itself. See the LICENSE file for further details.
7              
8             package Filesys::POSIX::Snapshot;
9              
10 1     1   1343784 use strict;
  1         2  
  1         33  
11 1     1   5 use warnings;
  1         2  
  1         32  
12              
13 1     1   4 use Filesys::POSIX::Bits;
  1         1  
  1         304  
14 1     1   5 use Filesys::POSIX::Path ();
  1         2  
  1         18  
15 1     1   354 use Filesys::POSIX::Snapshot::Inode ();
  1         2  
  1         16  
16              
17 1     1   5 use Filesys::POSIX::Error qw(throw);
  1         1  
  1         155  
18              
19             =head1 NAME
20              
21             Filesys::POSIX::Snapshot - Create and operate on filesystem snapshots
22              
23             =head1 SYNOPSIS
24              
25             use Filesys::POSIX::Snapshot;
26              
27             ...
28              
29             $fs->mkpath('/snapshots/1');
30              
31             $fs->mount(Filesys::POSIX::Snapshot->new, '/snapshots/1',
32             'path' => '/'
33             );
34              
35             =head1 DESCRIPTION
36              
37             This module implements a sort of snapshotting, or copy-on-write, mechanism that
38             allows for the manipulation of any part of a filesystem in an isolated manner
39             that does not affect the original data.
40              
41             Depending on mount arguments, directory hierarchies are copied into memory as
42             they are encountered, or are copied entirely into memory. Regular files are
43             duplicated only when they are opened with C<$O_WRONLY> or C<$O_RDWR> flags.
44              
45             =head1 MOUNT ARGUMENTS
46              
47             The following mount arguments are accepted by L.
48              
49             The following value is mandatory:
50              
51             =over
52              
53             =item C
54              
55             The path within the current virtual filesystem which the snapshot will be based
56             on.
57              
58             =back
59              
60             The following value is not mandatory:
61              
62             =over
63              
64             =item C
65              
66             When set to a true value, the entire hierarchy of directory listings and inodes
67             will be duplicated into memory from its source specified in the C value.
68              
69             =back
70              
71             =head1 CREATING A NEW FILESYSTEM
72              
73             =over
74              
75             =item Cnew>
76              
77             Create a new, uninitialized snapshot filesystem object.
78              
79             =back
80              
81             =cut
82              
83             sub new {
84 5     5 1 38 return bless {}, shift;
85             }
86              
87             =head1 INITIALIZATION
88              
89             =over
90              
91             =item C<$fs-Einit(%data)>
92              
93             Initializes the new snapshot filesystem. A reference to the C<%data> structure
94             will be retained in the filesystem object.
95              
96             Exceptions will be thrown for the following:
97              
98             =over
99              
100             =item * EINVAL (Invalid argument)
101              
102             No C> value was specified.
103              
104             =item * ENOENT (No such file or directory)
105              
106             The path specified in mount argument C> does not exist within the
107             current virtual filesystem.
108              
109             =item * ENOTDIR (Not a directory)
110              
111             The path specified in mount argument C> is not a directory.
112              
113             =back
114              
115             =back
116              
117             =cut
118              
119             sub init {
120 5     5 1 12 my ( $self, %data ) = @_;
121              
122 5 100       15 my $path = $data{'path'} or throw &Errno::EINVAL;
123 4         10 my $inode = $data{'fs'}->stat($path);
124              
125 4 100       11 throw &Errno::ENOTDIR unless $inode->dir;
126              
127 3         9 $self->{'flags'} = \%data;
128              
129 3         15 my $root = Filesys::POSIX::Snapshot::Inode->from_inode( $inode, 'dev' => $self );
130              
131 3         3 $self->{'root'} = $root;
132 3         4 $root->{'parent'} = $root;
133              
134 3         6 return $self;
135             }
136              
137             1;
138              
139             __END__