| .TH LOSETUP 8 "November 2015" "util-linux" "System Administration" |
| .SH NAME |
| losetup \- set up and control loop devices |
| .SH SYNOPSIS |
| .ad l |
| Get info: |
| .sp |
| .in +5 |
| .B losetup |
| [\fIloopdev\fP] |
| .sp |
| .B losetup -l |
| .RB [ \-a ] |
| .sp |
| .B losetup -j |
| .I file |
| .RB [ \-o |
| .IR offset ] |
| .sp |
| .in -5 |
| Detach a loop device: |
| .sp |
| .in +5 |
| .B "losetup \-d" |
| .IR loopdev ... |
| .sp |
| .in -5 |
| Detach all associated loop devices: |
| .sp |
| .in +5 |
| .B "losetup \-D" |
| .sp |
| .in -5 |
| Set up a loop device: |
| .sp |
| .in +5 |
| .B losetup |
| .RB [ \-o |
| .IR offset ] |
| .RB [ \-\-sizelimit |
| .IR size ] |
| .RB [ \-\-sector\-size |
| .IR size ] |
| .in +8 |
| .RB [ \-Pr ] |
| .RB [ \-\-show ] " \-f" | \fIloopdev\fP |
| .I file |
| .sp |
| .in -13 |
| Resize a loop device: |
| .sp |
| .in +5 |
| .B "losetup \-c" |
| .I loopdev |
| .in -5 |
| .ad b |
| .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 |
| \fIloopdev\fP argument is given, the status of the corresponding loop |
| 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 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. |
| |
| .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" |
| 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. |
| .IP "\fB\-\-sizelimit \fIsize\fP" |
| The data end is set to no more than \fIsize\fP bytes after the data start. |
| .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 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 |
| .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 |
| determining the status of the device. |
| |
| .SH FILES |
| .TP |
| .I /dev/loop[0..N] |
| loop block devices |
| .TP |
| .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=1024k count=10 |
| # losetup --find --show ~/file.img |
| /dev/loop0 |
| # mkfs -t ext2 /dev/loop0 |
| # mount /dev/loop0 /mnt |
| ... |
| # 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 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 |
| https://www.kernel.org/pub/linux/utils/util-linux/. |