NAME

       cow-shell - Start a copy-on-write session and invoke a shell.

SYNOPSIS

       cow-shell [commandline]

DESCRIPTION

       cow-shell Executes specified command with 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.

EXAMPLES

       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.

       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 .ilist files, through -i or -I option.

FILES

       .ilist Generated dynamically in the current directory.  The file contains the list of i-node numbers that
              should be protected from write operation.

       /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.

       /bin/cp
              Used for copying.  Requires GNU option -a to be functional.

ENVIRONMENT

       COWDANCER_ILISTFILE
              The path to the current .ilist file.

       COWDANCER_IGNORE
              Used internally to work around infinite loops.  It will be unset.

       LD_PRELOAD
              Utilized to preload libcowdancer.so

       COWDANCER_DEBUG
              Debugging option.  Enables debug messages.  cowdancer will give verbose debug messages in standard
              error output.

       COWDANCER_SO
              Debugging option.  Specifies a different path for libcowdancer.so.

       COWDANCER_REUSE=yes
              Enables reuse of cowdancer .ilist file found for consecutive runs of cow-shell.

RETURN VALUE

       The  functions  that  are  overridden  with  cowdancer will give an errno value of 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.

RESTRICTIONS

       Can only support directories that are scanned by 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 .ilist file around.

AUTHOR

       Junichi Uekawa (dancer@debian.org)

       Upstream page is available at http://www.netfort.gr.jp/~dancer/software/cowdancer.html

SEE ALSO

       cowdancer-ilistcreate (1)

cowdancer                                          2006 Jan 25                                      cow-shell(1)