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