Debian Codegraph @

upstream/debian-unstable/man4/loop.4

raw
1 .\" Copyright 2002, Urs Thuermann <[email protected]>
2 .\" Copyright 2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH loop 4 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 loop, loop-control \- loop devices
10 .SH SYNOPSIS
11 .nf
12 #include <linux/loop.h>
13 .fi
14 .SH DESCRIPTION
15 The loop device is a block device that maps its data blocks not to a
16 physical device such as a hard disk or optical disk drive,
17 but to the blocks of
18 a regular file in a filesystem or to another block device.
19 This can be useful for example to provide a block device for a filesystem
20 image stored in a file, so that it can be mounted with the
21 .BR mount (8)
22 command.
23 You could do
24 .P
25 .in +4n
26 .EX
27 .RB $ " dd if=/dev/zero of=file.img bs=1MiB count=10" ;
28 .RB $ " sudo losetup /dev/loop4 file.img" ;
29 .RB $ " sudo mkfs \-t ext4 /dev/loop4" ;
30 .RB $ " sudo mkdir /myloopdev" ;
31 .RB $ " sudo mount /dev/loop4 /myloopdev" ;
32 .EE
33 .in
34 .P
35 See
36 .BR losetup (8)
37 for another example.
38 .P
39 A transfer function can be specified for each loop device for
40 encryption and decryption purposes.
41 .P
42 The following
43 .BR ioctl (2)
44 operations are provided by the loop block device:
45 .TP
46 .B LOOP_SET_FD
47 Associate the loop device with the open file whose file descriptor is
48 passed as the (third)
49 .BR ioctl (2)
50 argument.
51 .TP
52 .B LOOP_CLR_FD
53 Disassociate the loop device from any file descriptor.
54 .TP
55 .B LOOP_SET_STATUS
56 Set the status of the loop device using the (third)
57 .BR ioctl (2)
58 argument.
59 This argument is a pointer to a
60 .I loop_info
61 structure, defined in
62 .I <linux/loop.h>
63 as:
64 .IP
65 .in +4n
66 .EX
67 struct loop_info {
68 int lo_number; /* ioctl r/o */
69 dev_t lo_device; /* ioctl r/o */
70 unsigned long lo_inode; /* ioctl r/o */
71 dev_t lo_rdevice; /* ioctl r/o */
72 int lo_offset;
73 int lo_encrypt_type;
74 int lo_encrypt_key_size; /* ioctl w/o */
75 int lo_flags; /* ioctl r/w (r/o before
76 Linux 2.6.25) */
77 char lo_name[LO_NAME_SIZE];
78 unsigned char lo_encrypt_key[LO_KEY_SIZE];
79 /* ioctl w/o */
80 unsigned long lo_init[2];
81 char reserved[4];
82 };
83 .EE
84 .in
85 .IP
86 The encryption type
87 .RI ( lo_encrypt_type )
88 should be one of
89 .BR LO_CRYPT_NONE ,
90 .BR LO_CRYPT_XOR ,
91 .BR LO_CRYPT_DES ,
92 .BR LO_CRYPT_FISH2 ,
93 .BR LO_CRYPT_BLOW ,
94 .BR LO_CRYPT_CAST128 ,
95 .BR LO_CRYPT_IDEA ,
96 .BR LO_CRYPT_DUMMY ,
97 .BR LO_CRYPT_SKIPJACK ,
98 or (since Linux 2.6.0)
99 .BR LO_CRYPT_CRYPTOAPI .
100 .IP
101 The
102 .I lo_flags
103 field is a bit mask that can include zero or more of the following:
104 .RS
105 .TP
106 .B LO_FLAGS_READ_ONLY
107 The loopback device is read-only.
108 .TP
109 .BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)"
110 .\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581
111 The loopback device will autodestruct on last close.
112 .TP
113 .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
114 .\" commit e03c8dd14915fabc101aa495828d58598dc5af98
115 Allow automatic partition scanning.
116 .TP
117 .BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)"
118 .\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3
119 Use direct I/O mode to access the backing file.
120 .RE
121 .IP
122 The only
123 .I lo_flags
124 that can be modified by
125 .B LOOP_SET_STATUS
126 are
127 .B LO_FLAGS_AUTOCLEAR
128 and
129 .BR LO_FLAGS_PARTSCAN .
130 .TP
131 .B LOOP_GET_STATUS
132 Get the status of the loop device.
133 The (third)
134 .BR ioctl (2)
135 argument must be a pointer to a
136 .IR "struct loop_info" .
137 .TP
138 .BR LOOP_CHANGE_FD " (since Linux 2.6.5)"
139 Switch the backing store of the loop device to the new file identified
140 file descriptor specified in the (third)
141 .BR ioctl (2)
142 argument, which is an integer.
143 This operation is possible only if the loop device is read-only and
144 the new backing store is the same size and type as the old backing store.
145 .TP
146 .BR LOOP_SET_CAPACITY " (since Linux 2.6.30)"
147 .\" commit 53d6660836f233df66490707365ab177e5fb2bb4
148 Resize a live loop device.
149 One can change the size of the underlying backing store and then use this
150 operation so that the loop driver learns about the new size.
151 This operation takes no argument.
152 .TP
153 .BR LOOP_SET_DIRECT_IO " (since Linux 4.10)"
154 .\" commit ab1cb278bc7027663adbfb0b81404f8398437e11
155 Set DIRECT I/O mode on the loop device, so that
156 it can be used to open backing file.
157 The (third)
158 .BR ioctl (2)
159 argument is an unsigned long value.
160 A nonzero represents direct I/O mode.
161 .TP
162 .BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)"
163 .\" commit 89e4fdecb51cf5535867026274bc97de9480ade5
164 Set the block size of the loop device.
165 The (third)
166 .BR ioctl (2)
167 argument is an unsigned long value.
168 This value must be a power of two in the range
169 [512,pagesize];
170 otherwise, an
171 .B EINVAL
172 error results.
173 .TP
174 .BR LOOP_CONFIGURE " (since Linux 5.8)"
175 .\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
176 Setup and configure all loop device parameters in a single step using
177 the (third)
178 .BR ioctl (2)
179 argument.
180 This argument is a pointer to a
181 .I loop_config
182 structure, defined in
183 .I <linux/loop.h>
184 as:
185 .IP
186 .in +4n
187 .EX
188 struct loop_config {
189 __u32 fd;
190 __u32 block_size;
191 struct loop_info64 info;
192 __u64 __reserved[8];
193 };
194 .EE
195 .in
196 .IP
197 In addition to doing what
198 .B LOOP_SET_STATUS
199 can do,
200 .B LOOP_CONFIGURE
201 can also be used to do the following:
202 .RS
203 .IP \[bu] 3
204 set the correct block size immediately by setting
205 .IR loop_config.block_size ;
206 .IP \[bu]
207 explicitly request direct I/O mode by setting
208 .B LO_FLAGS_DIRECT_IO
209 in
210 .IR loop_config.info.lo_flags ;
211 and
212 .IP \[bu]
213 explicitly request read-only mode by setting
214 .B LO_FLAGS_READ_ONLY
215 in
216 .IR loop_config.info.lo_flags .
217 .RE
218 .P
219 Since Linux 2.6, there are two new
220 .BR ioctl (2)
221 operations:
222 .TP
223 .B LOOP_SET_STATUS64
224 .TQ
225 .B LOOP_GET_STATUS64
226 These are similar to
227 .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS
228 described above but use the
229 .I loop_info64
230 structure,
231 which has some additional fields and a larger range for some other fields:
232 .IP
233 .in +4n
234 .EX
235 struct loop_info64 {
236 uint64_t lo_device; /* ioctl r/o */
237 uint64_t lo_inode; /* ioctl r/o */
238 uint64_t lo_rdevice; /* ioctl r/o */
239 uint64_t lo_offset;
240 uint64_t lo_sizelimit; /* bytes, 0 == max available */
241 uint32_t lo_number; /* ioctl r/o */
242 uint32_t lo_encrypt_type;
243 uint32_t lo_encrypt_key_size; /* ioctl w/o */
244 uint32_t lo_flags; i /* ioctl r/w (r/o before
245 Linux 2.6.25) */
246 uint8_t lo_file_name[LO_NAME_SIZE];
247 uint8_t lo_crypt_name[LO_NAME_SIZE];
248 uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
249 uint64_t lo_init[2];
250 };
251 .EE
252 .in
253 .SS /dev/loop-control
254 Since Linux 3.1,
255 .\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844
256 the kernel provides the
257 .I /dev/loop\-control
258 device, which permits an application to dynamically find a free device,
259 and to add and remove loop devices from the system.
260 To perform these operations, one first opens
261 .I /dev/loop\-control
262 and then employs one of the following
263 .BR ioctl (2)
264 operations:
265 .TP
266 .B LOOP_CTL_GET_FREE
267 Allocate or find a free loop device for use.
268 On success, the device number is returned as the result of the call.
269 This operation takes no argument.
270 .TP
271 .B LOOP_CTL_ADD
272 Add the new loop device whose device number is specified
273 as a long integer in the third
274 .BR ioctl (2)
275 argument.
276 On success, the device index is returned as the result of the call.
277 If the device is already allocated, the call fails with the error
278 .BR EEXIST .
279 .TP
280 .B LOOP_CTL_REMOVE
281 Remove the loop device whose device number is specified
282 as a long integer in the third
283 .BR ioctl (2)
284 argument.
285 On success, the device number is returned as the result of the call.
286 If the device is in use, the call fails with the error
287 .BR EBUSY .
288 .SH FILES
289 .TP
290 .I /dev/loop*
291 The loop block special device files.
292 .SH EXAMPLES
293 The program below uses the
294 .I /dev/loop\-control
295 device to find a free loop device, opens the loop device,
296 opens a file to be used as the underlying storage for the device,
297 and then associates the loop device with the backing store.
298 The following shell session demonstrates the use of the program:
299 .P
300 .in +4n
301 .EX
302 .RB $ " dd if=/dev/zero of=file.img bs=1MiB count=10" ;
303 10+0 records in
304 10+0 records out
305 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
306 .RB $ " sudo ./mnt_loop file.img" ;
307 loopname = /dev/loop5
308 .EE
309 .in
310 .SS Program source
311 \&
312 .EX
313 #include <err.h>
314 #include <fcntl.h>
315 #include <linux/loop.h>
316 #include <sys/ioctl.h>
317 #include <stdio.h>
318 #include <stdlib.h>
319 #include <unistd.h>
320 \&
321 int
322 main(int argc, char *argv[])
323 {
324 int loopctlfd, loopfd, backingfile;
325 long devnr;
326 char loopname[4096];
327 \&
328 if (argc != 2) {
329 fprintf(stderr, "Usage: %s backing\-file\[rs]n", argv[0]);
330 exit(EXIT_FAILURE);
331 }
332 \&
333 loopctlfd = open("/dev/loop\-control", O_RDWR);
334 if (loopctlfd == \-1)
335 err(EXIT_FAILURE, "open: /dev/loop\-control");
336 \&
337 devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
338 if (devnr == \-1)
339 err(EXIT_FAILURE, "ioctl\-LOOP_CTL_GET_FREE");
340 \&
341 sprintf(loopname, "/dev/loop%ld", devnr);
342 printf("loopname = %s\[rs]n", loopname);
343 \&
344 loopfd = open(loopname, O_RDWR);
345 if (loopfd == \-1)
346 err(EXIT_FAILURE, "open: loopname");
347 \&
348 backingfile = open(argv[1], O_RDWR);
349 if (backingfile == \-1)
350 err(EXIT_FAILURE, "open: backing\-file");
351 \&
352 if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1)
353 err(EXIT_FAILURE, "ioctl\-LOOP_SET_FD");
354 \&
355 exit(EXIT_SUCCESS);
356 }
357 .EE
358 .SH SEE ALSO
359 .BR losetup (8),
360 .BR mount (8)