summaryrefslogtreecommitdiff
path: root/usr.sbin/pkg_add/pod/OpenBSD::Vstat.pod
blob: d318190179681a15a616c3c608b2a7271ebf9bf5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
$OpenBSD: OpenBSD::Vstat.pod,v 1.3 2007/04/17 00:00:55 espie Exp $

=head1 NAME

OpenBSD::Vstat - virtual filesystem for C<pkg_add(1)> simulations

=head1 SYNOPSIS

    use OpenBSD::Vstat;

    $h = OpenBSD::Vstat::add($filename, $size, $tag);
    OpenBSD::Vstat::remove($filename, $size);
    $e = OpenBSD::Vstat::vexists($filename);
    OpenBSD::Vstat::tally();

=head1 DESCRIPTION

C<OpenBSD::Vstat> provides functions to layout a virtual file system on top
of the real one.  This is generally used to simulate file system manipulations
before doing them for real.

The functions C<OpenBSD::Vstat::add> (respectively
C<OpenBSD::Vstat::remove>) can be used to add a filename to
the file system (resp. remove a filename from the file system).  
The function C<OpenBSD::Vstat:vexists> looks for
a given filename: first it checks if it has been added or removed in
the virtual filesystem. Failing that, it looks into the real file system
using C<-e>.

Both C<OpenBSD::Vstat::add> and C<OpenBSD::Vstat::remove> also know about
Unix filesystem semantics, namely C<mount(8)> points and disk usage.
They return a small object corresponding to the filename's file system with
the following fields

=over 8

=item ro

defined if the filesystem is read-only. Usually hard to add files there.

=item nodev

defined if the filesystem forbids devices.

=item noexec

defined if the filesystem forbids execution.

=item nosuid

defined if the filesystem forbids SUID files.

=item avail()

returns the number of bytes still available on the filesystem.

=back

C<OpenBSD::Vstat::vexists> returns a true value if the filename exists.
If it is a virtual name added through C<OpenBSD::Vstat::add>, it returns
the C<$tag> specified as an optional argument. Otherwise, it returns 1.

C<OpenBSD::Vstat:tally> displays a summary of filesystem manipulations
after a series of additions and removals.

Due to the way packages get updated, size modifications through 
C<OpenBSD::Vstat::remove> are delayed until the next call to
C<OpenBSD::Vstat::synchronize>: old files must be removed before
adding the new files in order to properly account for collisions,
but the old files occupy disk space while the new package gets extracted.

=head1 CAVEATS

The API to this module may change.

=head1 BUGS AND LIMITATIONS

C<OpenBSD::Vstat> now handles C<chroot(8)> situations gracefully, but
it doesn't know about symbolic links to directories and will report bogus
results in complicated cases.