1LOOP(4) Linux Programmer's Manual LOOP(4)
2
6 loop, loop-control - loop devices
7
9 #include <linux/loop.h>
10
12 The loop device is a block device that maps its data blocks not to a
13 physical device such as a hard disk or optical disk drive, but to the
14 blocks of a regular file in a filesystem or to another block device.
15 This can be useful for example to provide a block device for a filesys‐
16 tem image stored in a file, so that it can be mounted with the mount(8)
17 command. You could do
18 $ dd if=/dev/zero of=file.img bs=1MiB count=10
20 $ sudo losetup /dev/loop4 file.img
21 $ sudo mkfs -t ext4 /dev/loop4
22 $ sudo mkdir /myloopdev
23 $ sudo mount /dev/loop4 /myloopdev
24 See losetup(8) for another example.
26 A transfer function can be specified for each loop device for encryp‐
28 tion and decryption purposes.
29 The following ioctl(2) operations are provided by the loop block de‐
31 vice:
32 LOOP_SET_FD
34 Associate the loop device with the open file whose file descrip‐
35 tor is passed as the (third) ioctl(2) argument.
36 LOOP_CLR_FD
38 Disassociate the loop device from any file descriptor.
39 LOOP_SET_STATUS
41 Set the status of the loop device using the (third) ioctl(2) ar‐
42 gument. This argument is a pointer to a loop_info structure,
43 defined in <linux/loop.h> as:
44 struct loop_info {
46 int lo_number; /* ioctl r/o */
47 dev_t lo_device; /* ioctl r/o */
48 unsigned long lo_inode; /* ioctl r/o */
49 dev_t lo_rdevice; /* ioctl r/o */
50 int lo_offset;
51 int lo_encrypt_type;
52 int lo_encrypt_key_size; /* ioctl w/o */
53 int lo_flags; /* ioctl r/w (r/o before
54 Linux 2.6.25) */
55 char lo_name[LO_NAME_SIZE];
56 unsigned char lo_encrypt_key[LO_KEY_SIZE];
57 /* ioctl w/o */
58 unsigned long lo_init[2];
59 char reserved[4];
60 };
61 The encryption type (lo_encrypt_type) should be one of
63 LO_CRYPT_NONE, LO_CRYPT_XOR, LO_CRYPT_DES, LO_CRYPT_FISH2,
64 LO_CRYPT_BLOW, LO_CRYPT_CAST128, LO_CRYPT_IDEA, LO_CRYPT_DUMMY,
65 LO_CRYPT_SKIPJACK, or (since Linux 2.6.0) LO_CRYPT_CRYPTOAPI.
66 The lo_flags field is a bit mask that can include zero or more
68 of the following:
69 LO_FLAGS_READ_ONLY
71 The loopback device is read-only.
72 LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
74 The loopback device will autodestruct on last close.
75 LO_FLAGS_PARTSCAN (since Linux 3.2)
77 Allow automatic partition scanning.
78 LO_FLAGS_DIRECT_IO (since Linux 4.10)
80 Use direct I/O mode to access the backing file.
81 The only lo_flags that can be modified by LOOP_SET_STATUS are
83 LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.
84 LOOP_GET_STATUS
86 Get the status of the loop device. The (third) ioctl(2) argu‐
87 ment must be a pointer to a struct loop_info.
88 LOOP_CHANGE_FD (since Linux 2.6.5)
90 Switch the backing store of the loop device to the new file
91 identified file descriptor specified in the (third) ioctl(2) ar‐
92 gument, which is an integer. This operation is possible only if
93 the loop device is read-only and the new backing store is the
94 same size and type as the old backing store.
95 LOOP_SET_CAPACITY (since Linux 2.6.30)
97 Resize a live loop device. One can change the size of the un‐
98 derlying backing store and then use this operation so that the
99 loop driver learns about the new size. This operation takes no
100 argument.
101 LOOP_SET_DIRECT_IO (since Linux 4.10)
103 Set DIRECT I/O mode on the loop device, so that it can be used
104 to open backing file. The (third) ioctl(2) argument is an un‐
105 signed long value. A nonzero represents direct I/O mode.
106 LOOP_SET_BLOCK_SIZE (since Linux 4.14)
108 Set the block size of the loop device. The (third) ioctl(2) ar‐
109 gument is an unsigned long value. This value must be a power of
110 two in the range [512,pagesize]; otherwise, an EINVAL error re‐
111 sults.
112 LOOP_CONFIGURE (since Linux 5.8)
114 Setup and configure all loop device parameters in a single step
115 using the (third) ioctl(2) argument. This argument is a pointer
116 to a loop_config structure, defined in <linux/loop.h> as:
117 struct loop_config {
119 __u32 fd;
120 __u32 block_size;
121 struct loop_info64 info;
122 __u64 __reserved[8];
123 };
124 In addition to doing what LOOP_SET_STATUS can do, LOOP_CONFIGURE
126 can also be used to do the following:
127 * set the correct block size immediately by setting loop_con‐
129 fig.block_size;
130 * explicitly request direct I/O mode by setting LO_FLAGS_DI‐
132 RECT_IO in loop_config.info.lo_flags; and
133 * explicitly request read-only mode by setting
135 LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.
136 Since Linux 2.6, there are two new ioctl(2) operations:
138 LOOP_SET_STATUS64, LOOP_GET_STATUS64
140 These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS de‐
141 scribed above but use the loop_info64 structure, which has some
142 additional fields and a larger range for some other fields:
143 struct loop_info64 {
145 uint64_t lo_device; /* ioctl r/o */
146 uint64_t lo_inode; /* ioctl r/o */
147 uint64_t lo_rdevice; /* ioctl r/o */
148 uint64_t lo_offset;
149 uint64_t lo_sizelimit; /* bytes, 0 == max available */
150 uint32_t lo_number; /* ioctl r/o */
151 uint32_t lo_encrypt_type;
152 uint32_t lo_encrypt_key_size; /* ioctl w/o */
153 uint32_t lo_flags; i /* ioctl r/w (r/o before
154 Linux 2.6.25) */
155 uint8_t lo_file_name[LO_NAME_SIZE];
156 uint8_t lo_crypt_name[LO_NAME_SIZE];
157 uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
158 uint64_t lo_init[2];
159 };
160 /dev/loop-control
162 Since Linux 3.1, the kernel provides the /dev/loop-control device,
163 which permits an application to dynamically find a free device, and to
164 add and remove loop devices from the system. To perform these opera‐
165 tions, one first opens /dev/loop-control and then employs one of the
166 following ioctl(2) operations:
167 LOOP_CTL_GET_FREE
169 Allocate or find a free loop device for use. On success, the
170 device number is returned as the result of the call. This oper‐
171 ation takes no argument.
172 LOOP_CTL_ADD
174 Add the new loop device whose device number is specified as a
175 long integer in the third ioctl(2) argument. On success, the
176 device index is returned as the result of the call. If the de‐
177 vice is already allocated, the call fails with the error EEXIST.
178 LOOP_CTL_REMOVE
180 Remove the loop device whose device number is specified as a
181 long integer in the third ioctl(2) argument. On success, the
182 device number is returned as the result of the call. If the de‐
183 vice is in use, the call fails with the error EBUSY.
184
186 /dev/loop*
187 The loop block special device files.
188
190 The program below uses the /dev/loop-control device to find a free loop
191 device, opens the loop device, opens a file to be used as the underly‐
192 ing storage for the device, and then associates the loop device with
193 the backing store. The following shell session demonstrates the use of
194 the program:
195 $ dd if=/dev/zero of=file.img bs=1MiB count=10
197 10+0 records in
198 10+0 records out
199 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
200 $ sudo ./mnt_loop file.img
201 loopname = /dev/loop5
202 Program source
204 #include <fcntl.h>
206 #include <linux/loop.h>
207 #include <sys/ioctl.h>
208 #include <stdio.h>
209 #include <stdlib.h>
210 #include <unistd.h>
211 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
213 } while (0)
214 int
216 main(int argc, char *argv[])
217 {
218 int loopctlfd, loopfd, backingfile;
219 long devnr;
220 char loopname[4096];
221 if (argc != 2) {
223 fprintf(stderr, "Usage: %s backing-file\n", argv[0]);
224 exit(EXIT_FAILURE);
225 }
226 loopctlfd = open("/dev/loop-control", O_RDWR);
228 if (loopctlfd == -1)
229 errExit("open: /dev/loop-control");
230 devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
232 if (devnr == -1)
233 errExit("ioctl-LOOP_CTL_GET_FREE");
234 sprintf(loopname, "/dev/loop%ld", devnr);
236 printf("loopname = %s\n", loopname);
237 loopfd = open(loopname, O_RDWR);
239 if (loopfd == -1)
240 errExit("open: loopname");
241 backingfile = open(argv[1], O_RDWR);
243 if (backingfile == -1)
244 errExit("open: backing-file");
245 if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
247 errExit("ioctl-LOOP_SET_FD");
248 exit(EXIT_SUCCESS);
250 }
251
253 losetup(8), mount(8)
254
256 This page is part of release 5.12 of the Linux man-pages project. A
257 description of the project, information about reporting bugs, and the
258 latest version of this page, can be found at
259 https://www.kernel.org/doc/man-pages/.
260Linux 2021-03-22 LOOP(4)