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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
.TH "cow\-shell" 1 "2006 Jan 25" "cowdancer" "cowdancer"
.SH "NAME"
cow\-shell \- Start a copy-on-write session and invoke a shell.
.SH SYNOPSIS
.BI "cow-shell [" "commandline" "]"
.SH DESCRIPTION
.B cow\-shell
Executes specified command with
.B cowdancer
or a shell if no command-line option is given.
Inside the cowdancer session, files under the current directory
are protected in a way so that a write operation to an i-node
which existed at the point of running cow-shell
is not modified.
Useful for managing hard-linked source-trees and
scratch-filesystems.
.SH "EXAMPLES"
.TP
.B "cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell "
Create a hardlinked tree, and cd into the newly created tree.
After invoking cow-shell inside that tree, a write operation
against a file that is hardlinked with the original tree
will be copied to a new file before write.
.TP
.B "cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell debuild"
Tries to run dpkg-buildpackage on the new tree,
to avoid damage to the original tree.
Configure debuild to ignore
.B ".ilist"
files, through
.B "-i"
or
.B "-I"
option.
.PP
.SH "FILES"
.TP
.B ".ilist"
Generated dynamically in the current directory.
The file contains the list of i-node numbers that should be
protected from write operation.
.TP
.B "/usr/lib/cowdancer/libcowdancer.so"
The shared library used internally that overrides some functions
that potentially write to files.
This library implements the COW feature and is preloaded with
LD_PRELOAD.
.TP
.B "/bin/cp"
Used for copying.
Requires GNU option
.B "\-a"
to be functional.
.SH "ENVIRONMENT"
.TP
.B "COWDANCER_ILISTFILE"
The path to the current
.B .ilist
file.
.TP
.B "COWDANCER_IGNORE"
Used internally to work around infinite loops.
It will be unset.
.TP
.B "LD_PRELOAD"
Utilized to preload
.B libcowdancer.so
.TP
.B "COWDANCER_DEBUG"
Debugging option.
Enables debug messages.
cowdancer will give verbose debug messages in standard error output.
.TP
.B "COWDANCER_SO"
Debugging option.
Specifies a different path for libcowdancer.so.
.TP
.B "COWDANCER_REUSE=yes"
Enables reuse of cowdancer .ilist file found for consecutive runs of
cow-shell.
.SH "RETURN VALUE"
The functions that are overridden with cowdancer will give an errno
value of
.B ENOMEM
when there is a problem.
System isn't really out of memory, but this error code is chosen
because this error is usually handled gracefully by applications.
.SH "RESTRICTIONS"
Can only support directories that are scanned by
.B cow-shell
command.
The operation is not semantically correct when files are originally
hardlinked, hardlinks are always broken.
Does not support anything when LD_PRELOAD trick does not work.
Does not work unless hardlinks are supported on the filesystem.
Not very user-friendly.
Leaves
.B ".ilist"
file around.
.SH "AUTHOR"
Junichi Uekawa (dancer@debian.org)
Upstream page is available at
.B "http://www.netfort.gr.jp/~dancer/software/cowdancer.html"
.SH "SEE ALSO"
.BR "cowdancer-ilistcreate (" 1 ")"
|
