1$OpenBSD: Vstat.pod,v 1.1 2020/12/20 15:30:58 daniel Exp $ 2 3=head1 NAME 4 5OpenBSD::Vstat - virtual filesystem for C<pkg_add(1)> simulations 6 7=head1 SYNOPSIS 8 9 use OpenBSD::Vstat; 10 11 my $v = OpenBSD::Vstat->new($state); 12 13 $h = $v->add($filename, $size, $tag); 14 $v->remove($filename, $size); 15 $e = $v->exists($filename); 16 $v->tally; 17 18=head1 DESCRIPTION 19 20C<OpenBSD::Vstat> provides methods to layout a virtual file system on top 21of the real one. This is generally used to simulate file system manipulations 22before doing them for real. 23 24The constructor C<new> expect a C<$state> object, that is, an object with 25C<$state-E<gt>{not}> and C<$state-E<gt>errsay> defined. 26 27Operations on the C<Vstat> object can modify C<$state-E<gt>{problems}> 28and C<$state-E<gt>{overflow}>. 29 30The method C<add> (respectively C<remove>) can be used to add a filename to 31the file system (resp. remove a filename from the file system). 32The method C<exists> looks for 33a given filename: first it checks if it has been added or removed in 34the virtual filesystem. Failing that, it looks into the real file system 35using C<-e>. 36 37Both C<add> and C<remove> also know about 38Unix filesystem semantics, namely C<mount(8)> points and disk usage. 39They return a small object corresponding to the filename's file system with 40the following methods 41 42=over 8 43 44=item ro 45 46defined if the filesystem is read-only. Usually hard to add files there. 47 48=item nodev 49 50defined if the filesystem forbids devices. 51 52=item noexec 53 54defined if the filesystem forbids execution. 55 56=item nosuid 57 58defined if the filesystem forbids SUID files. 59 60=item avail 61 62returns the number of bytes still available on the filesystem. 63 64=back 65 66C<exists> returns a true value if the filename exists. 67If it is a virtual name added through C<add>, it returns 68the C<$tag> specified as an optional argument. Otherwise, it returns 1. 69 70C<tally> displays a summary of filesystem manipulations 71after a series of additions and removals. 72 73Due to the way packages get updated, size modifications through 74C<remove> are delayed until the next call to 75C<synchronize>: old files must be removed before 76adding the new files in order to properly account for collisions, 77but the old files occupy disk space while the new package gets extracted. 78 79Modifications to the virtual file system are stored until a call to 80C<synchronize>, which assumes the real file system will get those changes 81(and thus we can forget them), or C<drop_changes>, which assumes the changes 82won't get through, thus providing transactional semantics. 83 84In case of file system overflow, C<remove_first> can be used to indicate 85file removal happens before the creation of new files. 86 87Typical use is as follows: 88 do lot of changes to the Vstat object 89 check for overflow. 90 if so, drop_changes. 91 redo the changes, with remove_first used instead of remove. 92 93In case C<$state-E<gt>{not}> is true, the real file system will never store 94changes, and thus the C<Vstat> object is layered to allow full transactional 95back-out. 96 97 98=head1 BUGS AND LIMITATIONS 99 100C<OpenBSD::Vstat> now handles C<chroot(8)> situations gracefully, but 101it doesn't know about symbolic links to directories and will report bogus 102results in complicated cases. 103 104C<OpenBSD::Vstat> needs an interface to deal with removed directories that 105get replaced with files. Currently, it will report a conflict. 106