---
name: "cow-shell"
section: "1"
platform: "linux"
package: "cowdancer"
version: "0.90"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cow-shell"
---

# cow-shell(1)

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

## 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**)**