man4/loop.4

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