-.TH LOSETUP 8 "July 2003" "util-linux" "System Administration"
+.TH LOSETUP 8 "November 2015" "util-linux" "System Administration"
.SH NAME
losetup \- set up and control loop devices
.SH SYNOPSIS
.sp
.in +5
.B losetup
-.I loopdev
+[\fIloopdev\fP]
.sp
-.B losetup -a
+.B losetup -l
+.RB [ \-a ]
.sp
.B losetup -j
.I file
.IR offset ]
.sp
.in -5
-Delete loop:
+Detach a loop device:
.sp
.in +5
.B "losetup \-d"
.IR loopdev ...
.sp
.in -5
-Delete all used loop devices:
+Detach all associated loop devices:
.sp
.in +5
.B "losetup \-D"
.sp
.in -5
-Print name of first unused loop device:
-.sp
-.in +5
-.B "losetup \-f"
-.sp
-.in -5
-Setup loop device:
+Set up a loop device:
.sp
.in +5
.B losetup
-.RB [{ \-e | \-E }
-.IR encryption ]
.RB [ \-o
.IR offset ]
.RB [ \-\-sizelimit
.IR size ]
+.RB [ \-\-sector\-size
+.IR size ]
.in +8
-.RB [ \-p
-.IR pfd ]
-.RB [ \-rP ]
-.RB { \-f [ \-\-show ]| \fIloopdev\fP }
+.RB [ \-Pr ]
+.RB [ \-\-show ] " \-f" | \fIloopdev\fP
.I file
.sp
.in -13
-Resize loop device:
+Resize a loop device:
.sp
.in +5
.B "losetup \-c"
.SH DESCRIPTION
.B losetup
is used to associate loop devices with regular files or block devices,
-to detach loop devices and to query the status of a loop device. If only the
+to detach loop devices, and to query the status of a loop device. If only the
\fIloopdev\fP argument is given, the status of the corresponding loop
-device is shown.
+device is shown. If no option is given, all loop devices are shown.
+.sp
+Note that the old output format (i.e., \fBlosetup -a\fR) with comma-delimited
+strings is deprecated in favour of the \fB--list\fR output format.
+.sp
+It's possible to create more independent loop devices for the same backing
+file.
+.B This setup may be dangerous, can cause data loss, corruption and overwrites.
+Use \fB\-\-nooverlap\fR with \fB\-\-find\fR during setup to avoid this problem.
.SH OPTIONS
-The \fIsize\fR and \fIoffset\fR arguments may be followed by binary (2^N)
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIsize\fR and \fIoffset\fR
+arguments may be followed by the multiplicative suffixes KiB (=1024),
+MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
+optional, e.g., "K" has the same meaning as "KiB") or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
-.IP "\fB\-a, \-\-all\fP"
-show status of all loop devices. Note that not all information are accessible
-for non-root users.
-.IP "\fB\-c, \-\-set-capacity\fP \fIloopdev\fP
-force loop driver to reread size of the file associated with the specified loop device
-.IP "\fB\-d, \-\-detach\fP \fIloopdev\fP..."
-detach the file or device associated with the specified loop device(s)
-.IP "\fB\-D, \-\-detach-all\fP"
-detach all associated loop devices
-.IP "\fB\-e, \-E, \-\-encryption \fIencryption_type\fP"
-enable data encryption with specified name or number
-.IP "\fB\-f, \-\-find\fP"
-find the first unused loop device. If a
-.I file
-argument is present, use this device. Otherwise, print its name
-.IP "\fB\-h, \-\-help\fP"
-print help
-.IP "\fB\-j, \-\-associated \fIfile\fP"
-show status of all loop devices associated with given
-.I file
-.IP "\fB\-o, \-\-offset \fIoffset\fP"
-the data start is moved \fIoffset\fP bytes into the specified file or
-device
-.IP "\fB\-\-sizelimit \fIsize\fP"
-the data end is set to no more than \fIsize\fP bytes after the data start
-.IP "\fB\-p, \-\-pass-fd \fInum\fP"
-read the passphrase from file descriptor with number
-.I num
-instead of from the terminal
-.IP "\fB\-P, \-\-partscan\fP"
-force kernel to scan partition table on newly created loop device
-.IP "\fB\-r, \-\-read-only\fP"
-setup read-only loop device
+.TP
+.BR \-a , " \-\-all"
+Show the status of all loop devices. Note that not all information is accessible
+for non-root users. See also \fB\-\-list\fR. The old output format (as printed
+without \fB--list)\fR is deprecated.
+.TP
+.BR \-d , " \-\-detach " \fIloopdev\fR...
+Detach the file or device associated with the specified loop device(s). Note
+that since Linux v3.7 kernel uses "lazy device destruction". The detach
+operation does not return EBUSY error anymore if device is actively used by
+system, but it is marked by autoclear flag and destroyed later.
+.TP
+.BR \-D , " \-\-detach\-all"
+Detach all associated loop devices.
+.TP
+.BR \-f , " \-\-find " "\fR[\fIfile\fR]"
+Find the first unused loop device. If a \fIfile\fR argument is present, use
+the found device as loop device. Otherwise, just print its name.
.IP "\fB\-\-show\fP"
-print device name if the
-.I -f
-option and a
-.I file
-argument are present.
-.IP "\fB\-v, \-\-verbose\fP"
-verbose mode
+Display the name of the assigned loop device if the \fB\-f\fP option and a
+\fIfile\fP argument are present.
+.TP
+.BR \-L , " \-\-nooverlap"
+Check for conflicts between loop devices to avoid situation when the same
+backing file is shared between more loop devices. If the file is already used
+by another device then re-use the device rather than a new one. The option
+makes sense only with \fB\-\-find\fP.
+.TP
+.BR \-j , " \-\-associated " \fIfile\fR " \fR[\fB\-o \fIoffset\fR]"
+Show the status of all loop devices associated with the given \fIfile\fR.
+.TP
+.BR \-o , " \-\-offset " \fIoffset
+The data start is moved \fIoffset\fP bytes into the specified file or device. The \fIoffset\fP
+may be followed by the multiplicative suffixes; see above.
+.IP "\fB\-\-sizelimit \fIsize\fP"
+The data end is set to no more than \fIsize\fP bytes after the data start. The \fIsize\fP
+may be followed by the multiplicative suffixes; see above.
+.TP
+.BR \-b , " \-\-sector-size " \fIsize
+Set the logical sector size of the loop device in bytes (since Linux 4.14). The
+option may be used when create a new loop device as well as stand-alone command
+to modify sector size of the already existing loop device.
+.TP
+.BR \-c , " \-\-set\-capacity " \fIloopdev
+Force the loop driver to reread the size of the file associated with the
+specified loop device.
+.TP
+.BR \-P , " \-\-partscan"
+Force the kernel to scan the partition table on a newly created loop device.
+.TP
+.BR \-r , " \-\-read\-only"
+Set up a read-only loop device.
+.TP
+.BR \-\-direct\-io [ =on | off ]
+Enable or disable direct I/O for the backing file. The optional argument
+can be either \fBon\fR or \fBoff\fR. If the argument is omitted, it defaults
+to \fBon\fR.
+.TP
+.BR \-v , " \-\-verbose"
+Verbose mode.
+.TP
+.BR \-l , " \-\-list"
+If a loop device or the \fB-a\fR option is specified, print the default columns
+for either the specified loop device or all loop devices; the default is to
+print info about all devices. See also \fB\-\-output\fP, \fB\-\-noheadings\fP,
+\fB\-\-raw\fP, and \fB\-\-json\fP.
+.TP
+.BR \-O , " \-\-output " \fIcolumn\fR[,\fIcolumn\fR]...
+Specify the columns that are to be printed for the \fB\-\-list\fP output.
+Use \fB\-\-help\fR to get a list of all supported columns.
+.TP
+.B \-\-output\-all
+Output all available columns.
+.TP
+.BR \-n , " \-\-noheadings"
+Don't print headings for \fB\-\-list\fP output format.
+.IP "\fB\-\-raw\fP"
+Use the raw \fB\-\-list\fP output format.
+.TP
+.BR \-J , " \-\-json"
+Use JSON format for \fB\-\-list\fP output.
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
.SH ENCRYPTION
-.B Cryptoloop is deprecated in favor of dm-crypt. For more details see
-.B cryptsetup (8). It is possible that all bug reports regarding to -E/-e
-.B options will be ignored.
-
-
-It is possible to specify transfer functions (for encryption/decryption
-or other purposes) using one of the
-.B \-E
-and
-.B \-e
-options.
-There are two mechanisms to specify the desired encryption: by number
-and by name. If an encryption is specified by number then one
-has to make sure that the Linux kernel knows about the encryption with that
-number, probably by patching the kernel. Standard numbers that are
-always present are 0 (no encryption) and 1 (XOR encryption).
-When the cryptoloop module is loaded (or compiled in), it uses number 18.
-This cryptoloop module will take the name of an arbitrary encryption type
-and find the module that knows how to perform that encryption.
+.B Cryptoloop is no longer supported in favor of dm-crypt.
+.B For more details see cryptsetup(8).
.SH RETURN VALUE
.B losetup
-returns 0 on success, nonzero on failure. When
+returns 0 on success, nonzero on failure. When
.B losetup
displays the status of a loop device, it returns 1 if the device
is not configured and 2 if an error occurred which prevented
-from determining the status of the device.
+determining the status of the device.
.SH FILES
.TP
.I /dev/loop[0..N]
loop block devices
.TP
-.I /dev/loop-cotrol
+.I /dev/loop-control
loop control device
.SH EXAMPLE
The following commands can be used as an example of using the loop device.
.nf
.IP
-# dd if=/dev/zero of=~/file.img bs=1MiB count=10
+# dd if=/dev/zero of=~/file.img bs=1024k count=10
# losetup --find --show ~/file.img
/dev/loop0
# mkfs -t ext2 /dev/loop0
# umount /dev/loop0
# losetup --detach /dev/loop0
.fi
+.SH ENVIRONMENT
+.IP LOOPDEV_DEBUG=all
+enables debug output.
.SH AUTHORS
-Karel Zak <kzak@redhat.com>, based on original version from
+Karel Zak <kzak@redhat.com>, based on the original version from
Theodore Ts'o <tytso@athena.mit.edu>
.SH AVAILABILITY
The losetup command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+https://www.kernel.org/pub/linux/utils/util-linux/.
projects / thirdparty / util-linux.git / blobdiff