'\" t
.\"     Title: disorderfs
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2015-08-21
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "DISORDERFS" "1" "2015\-08\-21" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
disorderfs \- FUSE filesystem that introduces non\-determinism
.SH "SYNOPSIS"
.sp
\fBdisorderfs\fR [\fIOPTIONS\fR\&...] \fIROOTDIR\fR \fIMOUNTPOINT\fR
.SH "DESCRIPTION"
.sp
\fBdisorderfs\fR is an overlay FUSE filesystem that introduces non\-determinism into filesystem metadata\&. For example, it can randomize the order in which directory entries are read\&. This is useful for detecting non\-determinism in the build process\&.
.sp
\fIROOTDIR\fR is the path to the underlying directory that is to be mirrored, and \fIMOUNTPOINT\fR is where the overlay should be mounted\&.
.SH "OPTIONS"
.sp
See fusermount(1), mount\&.fuse(8), and mount(8) for a full list of options\&.
.sp
Options specific to \fBdisorderfs\fR:
.PP
\fB\-\-multi\-user=yes|no\fR
.RS 4
Whether or not to allow other users to access the overlay mount (default: no)\&. When enabled, disorderfs accesses the underlying file with the same credentials (user ID, group ID, supplemental group list) as the process accessing the overlaid file\&. This is different from FUSE\(cqs
\fBallow_other\fR
option, which allows other users access, but causes disorderfs to access the underlying filesystem with the credentials of the user running disorderfs, which is usually undesirable\&.

\fB\-\-multi\-user=yes\fR
requires disorderfs to run as root\&.
.RE
.PP
\fB\-\-shuffle\-dirents=yes|no\fR
.RS 4
Whether or not to randomly shuffle directory entries (default: no)\&. The directory entries are shuffled every time the directory is read, so repeated reads of the same directory will probably return different results\&.
.RE
.PP
\fB\-\-reverse\-dirents=yes|no\fR
.RS 4
Whether or not to return directory entries in reverse order (default: yes)\&.
.RE
.PP
\fB\-\-sort\-dirents=yes|no\fR
.RS 4
Whether or not to return directory entries in sorted order (default: no)\&.

Note that you need to explicitly override the default
\fB\-\-reverse\-dirents=no\fR
to get results in expected order\&.
.RE
.PP
\fB\-\-pad\-blocks=\fR\fB\fIN\fR\fR
.RS 4
Add
\fIN\fR
to the st_blocks field in struct stat(2) (default: 1)\&.
.RE
.PP
\fB\-\-share\-locks=yes|no\fR
.RS 4
Whether or not to share locks between disorderfs and the underlying filesystem (default: no)\&. When this option is enabled, locks created on the underlying filesystem are visible within disorderfs, and vice\-versa\&. When this option is disabled, locks still work within disorderfs, but if one process accesses the underlying filesystem directly, and another process accesses through disorderfs, they won\(cqt see each others\*(Aq locks\&.

Lock sharing is currently buggy, so it is disabled by default\&.
.RE
.PP
\fB\-\-help\fR, \fB\-h\fR
.RS 4
Display help\&.
.RE
.PP
\fB\-\-version\fR, \fB\-V\fR
.RS 4
Display the version\&.
.RE
.SH "BUGS"
.sp
\fB\-\-share\-locks=yes\fR is currently buggy: programs may report that a file is locked when it really isn\(cqt\&.
.SH "EXAMPLE"
.sp
If you are attempting to test a Reproducible Builds issue, it is recommended you use \fB\-\-sort\-dirents=yes\fR instead of \fB\-\-shuffle\-dirents=yes\fR to ensure that any difference between builds is deterministic in itself\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
$ mkdir rootdir sorted reversed
$ touch rootdir/a rootdir/b rootdir/c \fB(1)\fR

$ disorderfs \-\-sort\-dirents=yes \-\-reverse\-dirents=no rootdir sorted \fB(2)\fR
$ ls \-f sorted
\&.  \&.\&.  a  b  c \fB(3)\fR

$ disorderfs \-\-sort\-dirents=yes \-\-reverse\-dirents=yes rootdir reversed \fB(4)\fR
$ ls \-f reversed
c  b  a  \&.\&.  \&. \fB(5)\fR
.fi
.if n \{\
.RE
.\}
.sp
.TS
tab(:);
r lw(\n(.lu*75u/100u).
\fB1.\fR\h'-2n':T{
First, we create some example files
T}
\fB2.\fR\h'-2n':T{
Mount
\fBrootdir\fR
in sorted mode\&...
T}
\fB3.\fR\h'-2n':T{
\&... and the results are in sorted order\&.
T}
\fB4.\fR\h'-2n':T{
We mount
\fBrootdir\fR
again, sorting the results in reversed order\&...
T}
\fB5.\fR\h'-2n':T{
\&... and the directory contents are returned in reverse\&.
T}
.TE
.sp
$ fusermount \-u sorted $ fusermount \-u reversed
.SH "AUTHORS"
.sp
Andrew Ayer <agwa@andrewayer\&.name> Chris Lamb <lamby@debian\&.org>