[thirdparty/util-linux.git] / sys-utils / losetup.8

.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.  Note that the
partition table parsing depends on sector sizes.  The default is sector size is 512 bytes,
otherwise you need to use the option \fB\-\-sector\-size\fR together with \fB\-\-partscan\fR.
.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/.
Commit	Line	Data
	1	.TH LOSETUP 8 "November 2015" "util-linux" "System Administration"
	2	.SH NAME
	3	losetup \- set up and control loop devices
	4	.SH SYNOPSIS
	5	.ad l
	6	Get info:
	7	.sp
	8	.in +5
	9	.B losetup
	10	[\fIloopdev\fP]
	11	.sp
	12	.B losetup \-l
	13	.RB [ \-a ]
	14	.sp
	15	.B losetup \-j
	16	.I file
	17	.RB [ \-o
	18	.IR offset ]
	19	.sp
	20	.in -5
	21	Detach a loop device:
	22	.sp
	23	.in +5
	24	.B "losetup \-d"
	25	.IR loopdev ...
	26	.sp
	27	.in -5
	28	Detach all associated loop devices:
	29	.sp
	30	.in +5
	31	.B "losetup \-D"
	32	.sp
	33	.in -5
	34	Set up a loop device:
	35	.sp
	36	.in +5
	37	.B losetup
	38	.RB [ \-o
	39	.IR offset ]
	40	.RB [ \-\-sizelimit
	41	.IR size ]
	42	.RB [ \-\-sector\-size
	43	.IR size ]
	44	.in +8
	45	.RB [ \-Pr ]
	46	.RB [ \-\-show ] " \-f" \| \fIloopdev\fP
	47	.I file
	48	.sp
	49	.in -13
	50	Resize a loop device:
	51	.sp
	52	.in +5
	53	.B "losetup \-c"
	54	.I loopdev
	55	.in -5
	56	.ad b
	57	.SH DESCRIPTION
	58	.B losetup
	59	is used to associate loop devices with regular files or block devices,
	60	to detach loop devices, and to query the status of a loop device. If only the
	61	\fIloopdev\fP argument is given, the status of the corresponding loop
	62	device is shown. If no option is given, all loop devices are shown.
	63	.sp
	64	Note that the old output format (i.e., \fBlosetup \-a\fR) with comma-delimited
	65	strings is deprecated in favour of the \fB\-\-list\fR output format.
	66	.sp
	67	It's possible to create more independent loop devices for the same backing
	68	file.
	69	.B This setup may be dangerous, can cause data loss, corruption and overwrites.
	70	Use \fB\-\-nooverlap\fR with \fB\-\-find\fR during setup to avoid this problem.
	71
	72	.SH OPTIONS
	73	The \fIsize\fR and \fIoffset\fR
	74	arguments may be followed by the multiplicative suffixes KiB (=1024),
	75	MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
	76	optional, e.g., "K" has the same meaning as "KiB") or the suffixes
	77	KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
	78
	79	.TP
	80	.BR \-a , " \-\-all"
	81	Show the status of all loop devices. Note that not all information is accessible
	82	for non-root users. See also \fB\-\-list\fR. The old output format (as printed
	83	without \fB\-\-list)\fR is deprecated.
	84	.TP
	85	.BR \-d , " \-\-detach " \fIloopdev\fR...
	86	Detach the file or device associated with the specified loop device(s). Note
	87	that since Linux v3.7 kernel uses "lazy device destruction". The detach
	88	operation does not return EBUSY error anymore if device is actively used by
	89	system, but it is marked by autoclear flag and destroyed later.
	90	.TP
	91	.BR \-D , " \-\-detach\-all"
	92	Detach all associated loop devices.
	93	.TP
	94	.BR \-f , " \-\-find " "\fR[\fIfile\fR]"
	95	Find the first unused loop device. If a \fIfile\fR argument is present, use
	96	the found device as loop device. Otherwise, just print its name.
	97	.IP "\fB\-\-show\fP"
	98	Display the name of the assigned loop device if the \fB\-f\fP option and a
	99	\fIfile\fP argument are present.
	100	.TP
	101	.BR \-L , " \-\-nooverlap"
	102	Check for conflicts between loop devices to avoid situation when the same
	103	backing file is shared between more loop devices. If the file is already used
	104	by another device then re-use the device rather than a new one. The option
	105	makes sense only with \fB\-\-find\fP.
	106	.TP
	107	.BR \-j , " \-\-associated " \fIfile\fR " \fR[\fB\-o \fIoffset\fR]"
	108	Show the status of all loop devices associated with the given \fIfile\fR.
	109	.TP
	110	.BR \-o , " \-\-offset " \fIoffset
	111	The data start is moved \fIoffset\fP bytes into the specified file or device. The \fIoffset\fP
	112	may be followed by the multiplicative suffixes; see above.
	113	.IP "\fB\-\-sizelimit \fIsize\fP"
	114	The data end is set to no more than \fIsize\fP bytes after the data start. The \fIsize\fP
	115	may be followed by the multiplicative suffixes; see above.
	116	.TP
	117	.BR \-b , " \-\-sector-size " \fIsize
	118	Set the logical sector size of the loop device in bytes (since Linux 4.14). The
	119	option may be used when create a new loop device as well as stand-alone command
	120	to modify sector size of the already existing loop device.
	121	.TP
	122	.BR \-c , " \-\-set\-capacity " \fIloopdev
	123	Force the loop driver to reread the size of the file associated with the
	124	specified loop device.
	125	.TP
	126	.BR \-P , " \-\-partscan"
	127	Force the kernel to scan the partition table on a newly created loop device. Note that the
	128	partition table parsing depends on sector sizes. The default is sector size is 512 bytes,
	129	otherwise you need to use the option \fB\-\-sector\-size\fR together with \fB\-\-partscan\fR.
	130	.TP
	131	.BR \-r , " \-\-read\-only"
	132	Set up a read-only loop device.
	133	.TP
	134	.BR \-\-direct\-io [ =on \| off ]
	135	Enable or disable direct I/O for the backing file. The optional argument
	136	can be either \fBon\fR or \fBoff\fR. If the argument is omitted, it defaults
	137	to \fBon\fR.
	138	.TP
	139	.BR \-v , " \-\-verbose"
	140	Verbose mode.
	141	.TP
	142	.BR \-l , " \-\-list"
	143	If a loop device or the \fB\-a\fR option is specified, print the default columns
	144	for either the specified loop device or all loop devices; the default is to
	145	print info about all devices. See also \fB\-\-output\fP, \fB\-\-noheadings\fP,
	146	\fB\-\-raw\fP, and \fB\-\-json\fP.
	147	.TP
	148	.BR \-O , " \-\-output " \fIcolumn\fR[,\fIcolumn\fR]...
	149	Specify the columns that are to be printed for the \fB\-\-list\fP output.
	150	Use \fB\-\-help\fR to get a list of all supported columns.
	151	.TP
	152	.B \-\-output\-all
	153	Output all available columns.
	154	.TP
	155	.BR \-n , " \-\-noheadings"
	156	Don't print headings for \fB\-\-list\fP output format.
	157	.IP "\fB\-\-raw\fP"
	158	Use the raw \fB\-\-list\fP output format.
	159	.TP
	160	.BR \-J , " \-\-json"
	161	Use JSON format for \fB\-\-list\fP output.
	162	.TP
	163	.BR \-V , " \-\-version"
	164	Display version information and exit.
	165	.TP
	166	.BR \-h , " \-\-help"
	167	Display help text and exit.
	168
	169	.SH ENCRYPTION
	170	.B Cryptoloop is no longer supported in favor of dm-crypt.
	171	.B For more details see cryptsetup(8).
	172
	173	.SH RETURN VALUE
	174	.B losetup
	175	returns 0 on success, nonzero on failure. When
	176	.B losetup
	177	displays the status of a loop device, it returns 1 if the device
	178	is not configured and 2 if an error occurred which prevented
	179	determining the status of the device.
	180
	181	.SH FILES
	182	.TP
	183	.I /dev/loop[0..N]
	184	loop block devices
	185	.TP
	186	.I /dev/loop-control
	187	loop control device
	188
	189	.SH EXAMPLE
	190	The following commands can be used as an example of using the loop device.
	191	.nf
	192	.IP
	193	# dd if=/dev/zero of=~/file.img bs=1024k count=10
	194	# losetup \-\-find \-\-show ~/file.img
	195	/dev/loop0
	196	# mkfs \-t ext2 /dev/loop0
	197	# mount /dev/loop0 /mnt
	198	...
	199	# umount /dev/loop0
	200	# losetup \-\-detach /dev/loop0
	201	.fi
	202	.SH ENVIRONMENT
	203	.IP LOOPDEV_DEBUG=all
	204	enables debug output.
	205	.SH AUTHORS
	206	Karel Zak <kzak@redhat.com>, based on the original version from
	207	Theodore Ts'o <tytso@athena.mit.edu>
	208	.SH AVAILABILITY
	209	The losetup command is part of the util-linux package and is available from
	210	https://www.kernel.org/pub/linux/utils/util-linux/.