man4/loop.4

   1 .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de)
   2 .\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH LOOP 4 2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 loop, loop-control \- loop devices
   9 .SH SYNOPSIS
  10 .nf
  11 #include <linux/loop.h>
  12 .fi
  13 .SH DESCRIPTION
  14 The loop device is a block device that maps its data blocks not to a
  15 physical device such as a hard disk or optical disk drive,
  16 but to the blocks of
  17 a regular file in a filesystem or to another block device.
  18 This can be useful for example to provide a block device for a filesystem
  19 image stored in a file, so that it can be mounted with the
  20 .BR mount (8)
  21 command.
  22 You could do
  23 .PP
  24 .in +4n
  25 .EX
  26 $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
  27 $ \fBsudo losetup /dev/loop4 file.img\fP
  28 $ \fBsudo mkfs \-t ext4 /dev/loop4\fP
  29 $ \fBsudo mkdir /myloopdev\fP
  30 $ \fBsudo mount /dev/loop4 /myloopdev\fP
  31 .EE
  32 .in
  33 .PP
  34 See
  35 .BR losetup (8)
  36 for another example.
  37 .PP
  38 A transfer function can be specified for each loop device for
  39 encryption and decryption purposes.
  40 .PP
  41 The following
  42 .BR ioctl (2)
  43 operations are provided by the loop block device:
  44 .TP
  45 .B LOOP_SET_FD
  46 Associate the loop device with the open file whose file descriptor is
  47 passed as the (third)
  48 .BR ioctl (2)
  49 argument.
  50 .TP
  51 .B LOOP_CLR_FD
  52 Disassociate the loop device from any file descriptor.
  53 .TP
  54 .B LOOP_SET_STATUS
  55 Set the status of the loop device using the (third)
  56 .BR ioctl (2)
  57 argument.
  58 This argument is a pointer to a
  59 .I loop_info
  60 structure, defined in
  61 .I <linux/loop.h>
  62 as:
  63 .IP
  64 .in +4n
  65 .EX
  66 struct loop_info {
  67     int           lo_number;      /* ioctl r/o */
  68     dev_t         lo_device;      /* ioctl r/o */
  69     unsigned long lo_inode;       /* ioctl r/o */
  70     dev_t         lo_rdevice;     /* ioctl r/o */
  71     int           lo_offset;
  72     int           lo_encrypt_type;
  73     int           lo_encrypt_key_size;  /* ioctl w/o */
  74     int           lo_flags;       /* ioctl r/w (r/o before
  75                                      Linux 2.6.25) */
  76     char          lo_name[LO_NAME_SIZE];
  77     unsigned char lo_encrypt_key[LO_KEY_SIZE];
  78                                   /* ioctl w/o */
  79     unsigned long lo_init[2];
  80     char          reserved[4];
  81 };
  82 .EE
  83 .in
  84 .IP
  85 The encryption type
  86 .RI ( lo_encrypt_type )
  87 should be one of
  88 .BR LO_CRYPT_NONE ,
  89 .BR LO_CRYPT_XOR ,
  90 .BR LO_CRYPT_DES ,
  91 .BR LO_CRYPT_FISH2 ,
  92 .BR LO_CRYPT_BLOW ,
  93 .BR LO_CRYPT_CAST128 ,
  94 .BR LO_CRYPT_IDEA ,
  95 .BR LO_CRYPT_DUMMY ,
  96 .BR LO_CRYPT_SKIPJACK ,
  97 or (since Linux 2.6.0)
  98 .BR LO_CRYPT_CRYPTOAPI .
  99 .IP
 100 The
 101 .I lo_flags
 102 field is a bit mask that can include zero or more of the following:
 103 .RS
 104 .TP
 105 .B LO_FLAGS_READ_ONLY
 106 The loopback device is read-only.
 107 .TP
 108 .BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)"
 109 .\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581
 110 The loopback device will autodestruct on last close.
 111 .TP
 112 .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
 113 .\" commit e03c8dd14915fabc101aa495828d58598dc5af98
 114 Allow automatic partition scanning.
 115 .TP
 116 .BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)"
 117 .\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3
 118 Use direct I/O mode to access the backing file.
 119 .RE
 120 .IP
 121 The only
 122 .I lo_flags
 123 that can be modified by
 124 .B LOOP_SET_STATUS
 125 are
 126 .B LO_FLAGS_AUTOCLEAR
 127 and
 128 .BR LO_FLAGS_PARTSCAN .
 129 .TP
 130 .B LOOP_GET_STATUS
 131 Get the status of the loop device.
 132 The (third)
 133 .BR ioctl (2)
 134 argument must be a pointer to a
 135 .IR "struct loop_info" .
 136 .TP
 137 .BR LOOP_CHANGE_FD " (since Linux 2.6.5)"
 138 Switch the backing store of the loop device to the new file identified
 139 file descriptor specified in the (third)
 140 .BR ioctl (2)
 141 argument, which is an integer.
 142 This operation is possible only if the loop device is read-only and
 143 the new backing store is the same size and type as the old backing store.
 144 .TP
 145 .BR LOOP_SET_CAPACITY " (since Linux 2.6.30)"
 146 .\" commit 53d6660836f233df66490707365ab177e5fb2bb4
 147 Resize a live loop device.
 148 One can change the size of the underlying backing store and then use this
 149 operation so that the loop driver learns about the new size.
 150 This operation takes no argument.
 151 .TP
 152 .BR LOOP_SET_DIRECT_IO " (since Linux 4.10)"
 153 .\" commit ab1cb278bc7027663adbfb0b81404f8398437e11
 154 Set DIRECT I/O mode on the loop device, so that
 155 it can be used to open backing file.
 156 The (third)
 157 .BR ioctl (2)
 158 argument is an unsigned long value.
 159 A nonzero represents direct I/O mode.
 160 .TP
 161 .BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)"
 162 .\" commit 89e4fdecb51cf5535867026274bc97de9480ade5
 163 Set the block size of the loop device.
 164 The (third)
 165 .BR ioctl (2)
 166 argument is an unsigned long value.
 167 This value must be a power of two in the range
 168 [512,pagesize];
 169 otherwise, an
 170 .B EINVAL
 171 error results.
 172 .TP
 173 .BR LOOP_CONFIGURE " (since Linux 5.8)"
 174 .\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
 175 Setup and configure all loop device parameters in a single step using
 176 the (third)
 177 .BR ioctl (2)
 178 argument.
 179 This argument is a pointer to a
 180 .I loop_config
 181 structure, defined in
 182 .I <linux/loop.h>
 183 as:
 184 .IP
 185 .in +4n
 186 .EX
 187 struct loop_config {
 188     uint32_t            fd;
 189     uint32_t            block_size;
 190     struct loop_info64  info;
 191     uint64_t            __reserved[8];
 192 };
 193 .EE
 194 .in
 195 .IP
 196 In addition to doing what
 197 .B LOOP_SET_STATUS
 198 can do,
 199 .B LOOP_CONFIGURE
 200 can also be used to do the following:
 201 .RS
 202 .IP * 2
 203 set the correct block size immediately by setting
 204 .IR loop_config.block_size ;
 205 .IP *
 206 explicitly request direct I/O mode by setting
 207 .B LO_FLAGS_DIRECT_IO
 208 in
 209 .IR loop_config.info.lo_flags ;
 210 and
 211 .IP *
 212 explicitly request read-only mode by setting
 213 .B LO_FLAGS_READ_ONLY
 214 in
 215 .IR loop_config.info.lo_flags .
 216 .RE
 217 .PP
 218 Since Linux 2.6, there are two new
 219 .BR ioctl (2)
 220 operations:
 221 .TP
 222 .BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64
 223 These are similar to
 224 .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS
 225 described above but use the
 226 .I loop_info64
 227 structure,
 228 which has some additional fields and a larger range for some other fields:
 229 .IP
 230 .in +4n
 231 .EX
 232 struct loop_info64 {
 233     uint64_t lo_device;           /* ioctl r/o */
 234     uint64_t lo_inode;            /* ioctl r/o */
 235     uint64_t lo_rdevice;          /* ioctl r/o */
 236     uint64_t lo_offset;
 237     uint64_t lo_sizelimit;  /* bytes, 0 == max available */
 238     uint32_t lo_number;           /* ioctl r/o */
 239     uint32_t lo_encrypt_type;
 240     uint32_t lo_encrypt_key_size; /* ioctl w/o */
 241     uint32_t lo_flags; i          /* ioctl r/w (r/o before
 242                                      Linux 2.6.25) */
 243     uint8_t  lo_file_name[LO_NAME_SIZE];
 244     uint8_t  lo_crypt_name[LO_NAME_SIZE];
 245     uint8_t  lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
 246     uint64_t lo_init[2];
 247 };
 248 .EE
 249 .in
 250 .SS /dev/loop-control
 251 Since Linux 3.1,
 252 .\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844
 253 the kernel provides the
 254 .I /dev/loop\-control
 255 device, which permits an application to dynamically find a free device,
 256 and to add and remove loop devices from the system.
 257 To perform these operations, one first opens
 258 .I /dev/loop\-control
 259 and then employs one of the following
 260 .BR ioctl (2)
 261 operations:
 262 .TP
 263 .B LOOP_CTL_GET_FREE
 264 Allocate or find a free loop device for use.
 265 On success, the device number is returned as the result of the call.
 266 This operation takes no argument.
 267 .TP
 268 .B LOOP_CTL_ADD
 269 Add the new loop device whose device number is specified
 270 as a long integer in the third
 271 .BR ioctl (2)
 272 argument.
 273 On success, the device index is returned as the result of the call.
 274 If the device is already allocated, the call fails with the error
 275 .BR EEXIST .
 276 .TP
 277 .B LOOP_CTL_REMOVE
 278 Remove the loop device whose device number is specified
 279 as a long integer in the third
 280 .BR ioctl (2)
 281 argument.
 282 On success, the device number is returned as the result of the call.
 283 If the device is in use, the call fails with the error
 284 .BR EBUSY .
 285 .SH FILES
 286 .TP
 287 .I /dev/loop*
 288 The loop block special device files.
 289 .SH EXAMPLES
 290 The program below uses the
 291 .I /dev/loop\-control
 292 device to find a free loop device, opens the loop device,
 293 opens a file to be used as the underlying storage for the device,
 294 and then associates the loop device with the backing store.
 295 The following shell session demonstrates the use of the program:
 296 .PP
 297 .in +4n
 298 .EX
 299 $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
 300 10+0 records in
 301 10+0 records out
 302 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
 303 $ \fBsudo ./mnt_loop file.img\fP
 304 loopname = /dev/loop5
 305 .EE
 306 .in
 307 .SS Program source
 308 \&
 309 .EX
 310 #include <fcntl.h>
 311 #include <linux/loop.h>
 312 #include <sys/ioctl.h>
 313 #include <stdio.h>
 314 #include <stdlib.h>
 315 #include <unistd.h>
 316
 317 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 318                         } while (0)
 319
 320 int
 321 main(int argc, char *argv[])
 322 {
 323     int loopctlfd, loopfd, backingfile;
 324     long devnr;
 325     char loopname[4096];
 326
 327     if (argc != 2) {
 328         fprintf(stderr, "Usage: %s backing\-file\en", argv[0]);
 329         exit(EXIT_FAILURE);
 330     }
 331
 332     loopctlfd = open("/dev/loop\-control", O_RDWR);
 333     if (loopctlfd == \-1)
 334         errExit("open: /dev/loop\-control");
 335
 336     devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
 337     if (devnr == \-1)
 338         errExit("ioctl\-LOOP_CTL_GET_FREE");
 339
 340     sprintf(loopname, "/dev/loop%ld", devnr);
 341     printf("loopname = %s\en", loopname);
 342
 343     loopfd = open(loopname, O_RDWR);
 344     if (loopfd == \-1)
 345         errExit("open: loopname");
 346
 347     backingfile = open(argv[1], O_RDWR);
 348     if (backingfile == \-1)
 349         errExit("open: backing\-file");
 350
 351     if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1)
 352         errExit("ioctl\-LOOP_SET_FD");
 353
 354     exit(EXIT_SUCCESS);
 355 }
 356 .EE
 357 .SH SEE ALSO
 358 .BR losetup (8),
 359 .BR mount (8)