1LOOP(4)                    Linux Programmer's Manual                   LOOP(4)
2
3
4

NAME

6       loop, loop-control - loop devices
7

SYNOPSIS

9       #include <linux/loop.h>
10

DESCRIPTION

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
19           $ 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
25       See losetup(8) for another example.
26
27       A transfer function can be specified for each loop device  for  encryp‐
28       tion and decryption purposes.
29
30       The  following  ioctl(2)  operations are provided by the loop block de‐
31       vice:
32
33       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
37       LOOP_CLR_FD
38              Disassociate the loop device from any file descriptor.
39
40       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
45                  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
62              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
67              The lo_flags field is a bit mask that can include zero  or  more
68              of the following:
69
70              LO_FLAGS_READ_ONLY
71                     The loopback device is read-only.
72
73              LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
74                     The loopback device will autodestruct on last close.
75
76              LO_FLAGS_PARTSCAN (since Linux 3.2)
77                     Allow automatic partition scanning.
78
79              LO_FLAGS_DIRECT_IO (since Linux 4.10)
80                     Use direct I/O mode to access the backing file.
81
82              The  only  lo_flags  that can be modified by LOOP_SET_STATUS are
83              LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.
84
85       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
89       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
96       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
102       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
107       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
113       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
118                  struct loop_config {
119                      __u32               fd;
120                      __u32               block_size;
121                      struct loop_info64  info;
122                      __u64               __reserved[8];
123                  };
124
125              In addition to doing what LOOP_SET_STATUS can do, LOOP_CONFIGURE
126              can also be used to do the following:
127
128              * set the correct block size immediately  by  setting  loop_con‐
129                fig.block_size;
130
131              * explicitly  request  direct  I/O  mode by setting LO_FLAGS_DI‐
132                RECT_IO in loop_config.info.lo_flags; and
133
134              * explicitly    request    read-only     mode     by     setting
135                LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.
136
137       Since Linux 2.6, there are two new ioctl(2) operations:
138
139       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
144                  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
161   /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
168       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
173       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
179       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

FILES

186       /dev/loop*
187              The loop block special device files.
188

EXAMPLES

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
196           $ 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
203   Program source
204
205       #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
212       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
213                               } while (0)
214
215       int
216       main(int argc, char *argv[])
217       {
218           int loopctlfd, loopfd, backingfile;
219           long devnr;
220           char loopname[4096];
221
222           if (argc != 2) {
223               fprintf(stderr, "Usage: %s backing-file\n", argv[0]);
224               exit(EXIT_FAILURE);
225           }
226
227           loopctlfd = open("/dev/loop-control", O_RDWR);
228           if (loopctlfd == -1)
229               errExit("open: /dev/loop-control");
230
231           devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
232           if (devnr == -1)
233               errExit("ioctl-LOOP_CTL_GET_FREE");
234
235           sprintf(loopname, "/dev/loop%ld", devnr);
236           printf("loopname = %s\n", loopname);
237
238           loopfd = open(loopname, O_RDWR);
239           if (loopfd == -1)
240               errExit("open: loopname");
241
242           backingfile = open(argv[1], O_RDWR);
243           if (backingfile == -1)
244               errExit("open: backing-file");
245
246           if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
247               errExit("ioctl-LOOP_SET_FD");
248
249           exit(EXIT_SUCCESS);
250       }
251

SEE ALSO

253       losetup(8), mount(8)
254

COLOPHON

256       This  page  is  part of release 5.10 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/.
260
261
262
263Linux                             2020-11-01                           LOOP(4)
Impressum