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
31       device:
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)
42              argument.  This argument is a pointer  to  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/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
61              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
66              The lo_flags field is a bit mask that can include zero  or  more
67              of the following:
68
69              LO_FLAGS_READ_ONLY
70                     The loopback device is read-only.
71
72              LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
73                     The loopback device will autodestruct on last close.
74
75              LO_FLAGS_PARTSCAN (since Linux 3.2)
76                     Allow automatic partition scanning.
77
78       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
82       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
89       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
95       Since Linux 2.6, there are two new ioctl(2) operations:
96
97       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
102                  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
118   /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
125       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
130       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
137       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

FILES

144       /dev/loop*
145              The loop block special device files.
146

EXAMPLE

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
154           $ 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
161   Program source
162
163       #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
170       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
171                               } while (0)
172
173       int
174       main(int argc, char *argv[])
175       {
176           int loopctlfd, loopfd, backingfile;
177           long devnr;
178           char loopname[4096];
179
180           if (argc != 2) {
181               fprintf(stderr, "Usage: %s backing-file\n", argv[0]);
182               exit(EXIT_FAILURE);
183           }
184
185           loopctlfd = open("/dev/loop-control", O_RDWR);
186           if (loopctlfd == -1)
187               errExit("open: /dev/loop-control");
188
189           devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
190           if (devnr == -1)
191               errExit("ioctl-LOOP_CTL_GET_FREE");
192
193           sprintf(loopname, "/dev/loop%ld", devnr);
194           printf("loopname = %s\n", loopname);
195
196           loopfd = open(loopname, O_RDWR);
197           if (loopfd == -1)
198               errExit("open: loopname");
199
200           backingfile = open(argv[1], O_RDWR);
201           if (backingfile == -1)
202               errExit("open: backing-file");
203
204           if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
205               errExit("ioctl-LOOP_SET_FD");
206
207           exit(EXIT_SUCCESS);
208       }
209

SEE ALSO

211       losetup(8), mount(8)
212

COLOPHON

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/.
218
219
220
221Linux                             2017-09-15                           LOOP(4)
Impressum