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/o */
54 char lo_name[LO_NAME_SIZE];
55 unsigned char lo_encrypt_key[LO_KEY_SIZE];
56 /* ioctl w/o */
57 unsigned long lo_init[2];
58 char reserved[4];
59 };
60 The encryption type (lo_encrypt_type) should be one of
62 LO_CRYPT_NONE, LO_CRYPT_XOR, LO_CRYPT_DES, LO_CRYPT_FISH2,
63 LO_CRYPT_BLOW, LO_CRYPT_CAST128, LO_CRYPT_IDEA, LO_CRYPT_DUMMY,
64 LO_CRYPT_SKIPJACK, or (since Linux 2.6.0) LO_CRYPT_CRYPTOAPI.
65 The lo_flags field is a bit mask that can include zero or more
67 of the following:
68 LO_FLAGS_READ_ONLY
70 The loopback device is read-only.
71 LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
73 The loopback device will autodestruct on last close.
74 LO_FLAGS_PARTSCAN (since Linux 3.2)
76 Allow automatic partition scanning.
77 LOOP_GET_STATUS
79 Get the status of the loop device. The (third) ioctl(2) argu‐
80 ment must be a pointer to a struct loop_info.
81 LOOP_CHANGE_FD (since Linux 2.6.5)
83 Switch the backing store of the loop device to the new file
84 identified file descriptor specified in the (third) ioctl(2)
85 argument, which is an integer. This operation is possible only
86 if the loop device is read-only and the new backing store is the
87 same size and type as the old backing store.
88 LOOP_SET_CAPACITY (since Linux 2.6.30)
90 Resize a live loop device. One can change the size of the
91 underlying backing store and then use this operation so that the
92 loop driver learns about the new size. This operation takes no
93 argument.
94 Since Linux 2.6, there are two new ioctl(2) operations:
96 LOOP_SET_STATUS64, LOOP_GET_STATUS64
98 These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS
99 described above but use the loop_info64 structure, which has
100 some additional fields and a larger range for some other fields:
101 struct loop_info64 {
103 uint64_t lo_device; /* ioctl r/o */
104 uint64_t lo_inode; /* ioctl r/o */
105 uint64_t lo_rdevice; /* ioctl r/o */
106 uint64_t lo_offset;
107 uint64_t lo_sizelimit;/* bytes, 0 == max available */
108 uint32_t lo_number; /* ioctl r/o */
109 uint32_t lo_encrypt_type;
110 uint32_t lo_encrypt_key_size; /* ioctl w/o */
111 uint32_t lo_flags; /* ioctl r/o */
112 uint8_t lo_file_name[LO_NAME_SIZE];
113 uint8_t lo_crypt_name[LO_NAME_SIZE];
114 uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
115 uint64_t lo_init[2];
116 };
117 /dev/loop-control
119 Since Linux 3.1, the kernel provides the /dev/loop-control device,
120 which permits an application to dynamically find a free device, and to
121 add and remove loop devices from the system. To perform these opera‐
122 tions, one first opens /dev/loop-control and then employs one of the
123 following ioctl(2) operations:
124 LOOP_CTL_GET_FREE
126 Allocate or find a free loop device for use. On success, the
127 device number is returned as the result of the call. This oper‐
128 ation takes no argument.
129 LOOP_CTL_ADD
131 Add the new loop device whose device number is specified as a
132 long integer in the third ioctl(2) argument. On success, the
133 device index is returned as the result of the call. If the
134 device is already allocated, the call fails with the error EEX‐
135 IST.
136 LOOP_CTL_REMOVE
138 Remove the loop device whose device number is specified as a
139 long integer in the third ioctl(2) argument. On success, the
140 device number is returned as the result of the call. If the
141 device is in use, the call fails with the error EBUSY.
142
144 /dev/loop*
145 The loop block special device files.
146
148 The program below uses the /dev/loop-control device to find a free loop
149 device, opens the loop device, opens a file to be used as the underly‐
150 ing storage for the device, and then associates the loop device with
151 the backing store. The following shell session demonstrates the use of
152 the program:
153 $ dd if=/dev/zero of=file.img bs=1MiB count=10
155 10+0 records in
156 10+0 records out
157 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
158 $ sudo ./mnt_loop file.img
159 loopname = /dev/loop5
160 Program source
162 #include <fcntl.h>
164 #include <linux/loop.h>
165 #include <sys/ioctl.h>
166 #include <stdio.h>
167 #include <stdlib.h>
168 #include <unistd.h>
169 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
171 } while (0)
172 int
174 main(int argc, char *argv[])
175 {
176 int loopctlfd, loopfd, backingfile;
177 long devnr;
178 char loopname[4096];
179 if (argc != 2) {
181 fprintf(stderr, "Usage: %s backing-file\n", argv[0]);
182 exit(EXIT_FAILURE);
183 }
184 loopctlfd = open("/dev/loop-control", O_RDWR);
186 if (loopctlfd == -1)
187 errExit("open: /dev/loop-control");
188 devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
190 if (devnr == -1)
191 errExit("ioctl-LOOP_CTL_GET_FREE");
192 sprintf(loopname, "/dev/loop%ld", devnr);
194 printf("loopname = %s\n", loopname);
195 loopfd = open(loopname, O_RDWR);
197 if (loopfd == -1)
198 errExit("open: loopname");
199 backingfile = open(argv[1], O_RDWR);
201 if (backingfile == -1)
202 errExit("open: backing-file");
203 if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
205 errExit("ioctl-LOOP_SET_FD");
206 exit(EXIT_SUCCESS);
208 }
209
211 losetup(8), mount(8)
212
214 This page is part of release 4.16 of the Linux man-pages project. A
215 description of the project, information about reporting bugs, and the
216 latest version of this page, can be found at
217 https://www.kernel.org/doc/man-pages/.
218Linux 2017-09-15 LOOP(4)