200 lines
5.5 KiB
Groff
200 lines
5.5 KiB
Groff
.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
|
|
.I loopdev
|
|
.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
|
|
Print the name of the first unused loop device:
|
|
.sp
|
|
.in +5
|
|
.B "losetup \-f"
|
|
.sp
|
|
.in -5
|
|
Set up a loop device:
|
|
.sp
|
|
.in +5
|
|
.B losetup
|
|
.RB [ \-o
|
|
.IR offset ]
|
|
.RB [ \-\-sizelimit
|
|
.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).
|
|
.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 \-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
|
|
.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/.
|