diff options
Diffstat (limited to 'sys-utils/losetup.8')
| -rw-r--r-- | sys-utils/losetup.8 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/sys-utils/losetup.8 b/sys-utils/losetup.8 new file mode 100644 index 0000000..c31d747 --- /dev/null +++ b/sys-utils/losetup.8 @@ -0,0 +1,208 @@ +.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. 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 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/. |