Debian Codegraph @

upstream/debian-trixie/man4/loop.4

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