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
31 device:
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)
42 argument. This argument is a pointer to 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 LOOP_GET_STATUS
80 Get the status of the loop device. The (third) ioctl(2) argu‐
81 ment must be a pointer to a struct loop_info.
82 LOOP_CHANGE_FD (since Linux 2.6.5)
84 Switch the backing store of the loop device to the new file
85 identified file descriptor specified in the (third) ioctl(2)
86 argument, which is an integer. This operation is possible only
87 if the loop device is read-only and the new backing store is the
88 same size and type as the old backing store.
89 LOOP_SET_CAPACITY (since Linux 2.6.30)
91 Resize a live loop device. One can change the size of the
92 underlying backing store and then use this operation so that the
93 loop driver learns about the new size. This operation takes no
94 argument.
95 LOOP_SET_DIRECT_IO (since Linux 4.10)
97 Set DIRECT I/O mode on the loop device, so that it can be used
98 to open backing file. The (third) ioctl(2) argument is an
99 unsigned long value. A non-zero represents direct I/O mode.
100 LOOP_SET_BLOCK_SIZE (since Linux 4.14)
102 Set the block size of the loop device. The (third) ioctl(2)
103 argument is an unsigned long value. This value must be a power
104 of two in the range [512,pagesize]; otherwise, an EINVAL error
105 results.
106 Since Linux 2.6, there are two new ioctl(2) operations:
108 LOOP_SET_STATUS64, LOOP_GET_STATUS64
110 These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS
111 described above but use the loop_info64 structure, which has
112 some additional fields and a larger range for some other fields:
113 struct loop_info64 {
115 uint64_t lo_device; /* ioctl r/o */
116 uint64_t lo_inode; /* ioctl r/o */
117 uint64_t lo_rdevice; /* ioctl r/o */
118 uint64_t lo_offset;
119 uint64_t lo_sizelimit; /* bytes, 0 == max available */
120 uint32_t lo_number; /* ioctl r/o */
121 uint32_t lo_encrypt_type;
122 uint32_t lo_encrypt_key_size; /* ioctl w/o */
123 uint32_t lo_flags; i /* ioctl r/w (r/o before
124 Linux 2.6.25) */
125 uint8_t lo_file_name[LO_NAME_SIZE];
126 uint8_t lo_crypt_name[LO_NAME_SIZE];
127 uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
128 uint64_t lo_init[2];
129 };
130 /dev/loop-control
132 Since Linux 3.1, the kernel provides the /dev/loop-control device,
133 which permits an application to dynamically find a free device, and to
134 add and remove loop devices from the system. To perform these opera‐
135 tions, one first opens /dev/loop-control and then employs one of the
136 following ioctl(2) operations:
137 LOOP_CTL_GET_FREE
139 Allocate or find a free loop device for use. On success, the
140 device number is returned as the result of the call. This oper‐
141 ation takes no argument.
142 LOOP_CTL_ADD
144 Add the new loop device whose device number is specified as a
145 long integer in the third ioctl(2) argument. On success, the
146 device index is returned as the result of the call. If the
147 device is already allocated, the call fails with the error EEX‐
148 IST.
149 LOOP_CTL_REMOVE
151 Remove the loop device whose device number is specified as a
152 long integer in the third ioctl(2) argument. On success, the
153 device number is returned as the result of the call. If the
154 device is in use, the call fails with the error EBUSY.
155
157 /dev/loop*
158 The loop block special device files.
159
161 The program below uses the /dev/loop-control device to find a free loop
162 device, opens the loop device, opens a file to be used as the underly‐
163 ing storage for the device, and then associates the loop device with
164 the backing store. The following shell session demonstrates the use of
165 the program:
166 $ dd if=/dev/zero of=file.img bs=1MiB count=10
168 10+0 records in
169 10+0 records out
170 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
171 $ sudo ./mnt_loop file.img
172 loopname = /dev/loop5
173 Program source
175 #include <fcntl.h>
177 #include <linux/loop.h>
178 #include <sys/ioctl.h>
179 #include <stdio.h>
180 #include <stdlib.h>
181 #include <unistd.h>
182 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
184 } while (0)
185 int
187 main(int argc, char *argv[])
188 {
189 int loopctlfd, loopfd, backingfile;
190 long devnr;
191 char loopname[4096];
192 if (argc != 2) {
194 fprintf(stderr, "Usage: %s backing-file\n", argv[0]);
195 exit(EXIT_FAILURE);
196 }
197 loopctlfd = open("/dev/loop-control", O_RDWR);
199 if (loopctlfd == -1)
200 errExit("open: /dev/loop-control");
201 devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
203 if (devnr == -1)
204 errExit("ioctl-LOOP_CTL_GET_FREE");
205 sprintf(loopname, "/dev/loop%ld", devnr);
207 printf("loopname = %s\n", loopname);
208 loopfd = open(loopname, O_RDWR);
210 if (loopfd == -1)
211 errExit("open: loopname");
212 backingfile = open(argv[1], O_RDWR);
214 if (backingfile == -1)
215 errExit("open: backing-file");
216 if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
218 errExit("ioctl-LOOP_SET_FD");
219 exit(EXIT_SUCCESS);
221 }
222
224 losetup(8), mount(8)
225
227 This page is part of release 5.07 of the Linux man-pages project. A
228 description of the project, information about reporting bugs, and the
229 latest version of this page, can be found at
230 https://www.kernel.org/doc/man-pages/.
231Linux 2020-06-09 LOOP(4)