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 2019-03-06 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 loop, loop-control \- loop devices
  29 .SH SYNOPSIS
  30 #include <linux/loop.h>
  31 .SH DESCRIPTION
  32 The loop device is a block device that maps its data blocks not to a
  33 physical device such as a hard disk or optical disk drive,
  34 but to the blocks of
  35 a regular file in a filesystem or to another block device.
  36 This can be useful for example to provide a block device for a filesystem
  37 image stored in a file, so that it can be mounted with the
  38 .BR mount (8)
  39 command.
  40 You could do
  41 .PP
  42 .in +4n
  43 .EX
  44 $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
  45 $ \fBsudo losetup /dev/loop4 file.img \fP
  46 $ \fBsudo mkfs -t ext4 /dev/loop4\fP
  47 $ \fBsudo mkdir /myloopdev\fP
  48 $ \fBsudo mount /dev/loop4 /myloopdev\fP
  49 .EE
  50 .in
  51 .PP
  52 See
  53 .BR losetup (8)
  54 for another example.
  55 .PP
  56 A transfer function can be specified for each loop device for
  57 encryption and decryption purposes.
  58 .PP
  59 The following
  60 .BR ioctl (2)
  61 operations are provided by the loop block device:
  62 .TP
  63 .B LOOP_SET_FD
  64 Associate the loop device with the open file whose file descriptor is
  65 passed as the (third)
  66 .BR ioctl (2)
  67 argument.
  68 .TP
  69 .B LOOP_CLR_FD
  70 Disassociate the loop device from any file descriptor.
  71 .TP
  72 .B LOOP_SET_STATUS
  73 Set the status of the loop device using the (third)
  74 .BR ioctl (2)
  75 argument.
  76 This argument is a pointer to
  77 .I loop_info
  78 structure, defined in
  79 .I <linux/loop.h>
  80 as:
  81 .IP
  82 .in +4n
  83 .EX
  84 struct loop_info {
  85     int           lo_number;            /* ioctl r/o */
  86     dev_t         lo_device;            /* ioctl r/o */
  87     unsigned long lo_inode;             /* ioctl r/o */
  88     dev_t         lo_rdevice;           /* ioctl r/o */
  89     int           lo_offset;
  90     int           lo_encrypt_type;
  91     int           lo_encrypt_key_size;  /* ioctl w/o */
  92     int           lo_flags;             /* ioctl r/o */
  93     char          lo_name[LO_NAME_SIZE];
  94     unsigned char lo_encrypt_key[LO_KEY_SIZE];
  95                                         /* ioctl w/o */
  96     unsigned long lo_init[2];
  97     char          reserved[4];
  98 };
  99 .EE
 100 .in
 101 .IP
 102 The encryption type
 103 .RI ( lo_encrypt_type )
 104 should be one of
 105 .BR LO_CRYPT_NONE ,
 106 .BR LO_CRYPT_XOR ,
 107 .BR LO_CRYPT_DES ,
 108 .BR LO_CRYPT_FISH2 ,
 109 .BR LO_CRYPT_BLOW ,
 110 .BR LO_CRYPT_CAST128 ,
 111 .BR LO_CRYPT_IDEA ,
 112 .BR LO_CRYPT_DUMMY ,
 113 .BR LO_CRYPT_SKIPJACK ,
 114 or (since Linux 2.6.0)
 115 .BR LO_CRYPT_CRYPTOAPI .
 116 .IP
 117 The
 118 .I lo_flags
 119 field is a bit mask that can include zero or more of the following:
 120 .RS
 121 .TP
 122 .BR LO_FLAGS_READ_ONLY
 123 The loopback device is read-only.
 124 .TP
 125 .BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)"
 126 .\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581
 127 The loopback device will autodestruct on last close.
 128 .TP
 129 .BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
 130 .\" commit e03c8dd14915fabc101aa495828d58598dc5af98
 131 Allow automatic partition scanning.
 132 .RE
 133 .TP
 134 .B LOOP_GET_STATUS
 135 Get the status of the loop device.
 136 The (third)
 137 .BR ioctl (2)
 138 argument must be a pointer to a
 139 .IR "struct loop_info" .
 140 .TP
 141 .BR LOOP_CHANGE_FD " (since Linux 2.6.5)"
 142 Switch the backing store of the loop device to the new file identified
 143 file descriptor specified in the (third)
 144 .BR ioctl (2)
 145 argument, which is an integer.
 146 This operation is possible only if the loop device is read-only and
 147 the new backing store is the same size and type as the old backing store.
 148 .TP
 149 .BR LOOP_SET_CAPACITY " (since Linux 2.6.30)"
 150 .\" commit 53d6660836f233df66490707365ab177e5fb2bb4
 151 Resize a live loop device.
 152 One can change the size of the underlying backing store and then use this
 153 operation so that the loop driver learns about the new size.
 154 This operation takes no argument.
 155 .PP
 156 Since Linux 2.6, there are two new
 157 .BR ioctl (2)
 158 operations:
 159 .TP
 160 .BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64
 161 These are similar to
 162 .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS
 163 described above but use the
 164 .I loop_info64
 165 structure,
 166 which has some additional fields and a larger range for some other fields:
 167 .IP
 168 .in +4n
 169 .EX
 170 struct loop_info64 {
 171     uint64_t lo_device;                   /* ioctl r/o */
 172     uint64_t lo_inode;                    /* ioctl r/o */
 173     uint64_t lo_rdevice;                  /* ioctl r/o */
 174     uint64_t lo_offset;
 175     uint64_t lo_sizelimit;/* bytes, 0 == max available */
 176     uint32_t lo_number;                   /* ioctl r/o */
 177     uint32_t lo_encrypt_type;
 178     uint32_t lo_encrypt_key_size;         /* ioctl w/o */
 179     uint32_t lo_flags;                    /* ioctl r/o */
 180     uint8_t  lo_file_name[LO_NAME_SIZE];
 181     uint8_t  lo_crypt_name[LO_NAME_SIZE];
 182     uint8_t  lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
 183     uint64_t lo_init[2];
 184 };
 185 .EE
 186 .in
 187 .SS /dev/loop-control
 188 Since Linux 3.1,
 189 .\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844
 190 the kernel provides the
 191 .I /dev/loop-control
 192 device, which permits an application to dynamically find a free device,
 193 and to add and remove loop devices from the system.
 194 To perform these operations, one first opens
 195 .IR /dev/loop-control
 196 and then employs one of the following
 197 .BR ioctl (2)
 198 operations:
 199 .TP
 200 .B LOOP_CTL_GET_FREE
 201 Allocate or find a free loop device for use.
 202 On success, the device number is returned as the result of the call.
 203 This operation takes no argument.
 204 .TP
 205 .B LOOP_CTL_ADD
 206 Add the new loop device whose device number is specified
 207 as a long integer in the third
 208 .BR ioctl (2)
 209 argument.
 210 On success, the device index is returned as the result of the call.
 211 If the device is already allocated, the call fails with the error
 212 .BR EEXIST .
 213 .TP
 214 .B LOOP_CTL_REMOVE
 215 Remove the loop device whose device number is specified
 216 as a long integer in the third
 217 .BR ioctl (2)
 218 argument.
 219 On success, the device number is returned as the result of the call.
 220 If the device is in use, the call fails with the error
 221 .BR EBUSY .
 222 .SH FILES
 223 .TP
 224 .IR /dev/loop*
 225 The loop block special device files.
 226 .SH EXAMPLE
 227 The program below uses the
 228 .I /dev/loop-control
 229 device to find a free loop device, opens the loop device,
 230 opens a file to be used as the underlying storage for the device,
 231 and then associates the loop device with the backing store.
 232 The following shell session demonstrates the use of the program:
 233 .PP
 234 .in +4n
 235 .EX
 236 $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
 237 10+0 records in
 238 10+0 records out
 239 10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
 240 $ \fBsudo ./mnt_loop file.img\fP
 241 loopname = /dev/loop5
 242 .EE
 243 .in
 244 .SS Program source
 245 \&
 246 .EX
 247 #include <fcntl.h>
 248 #include <linux/loop.h>
 249 #include <sys/ioctl.h>
 250 #include <stdio.h>
 251 #include <stdlib.h>
 252 #include <unistd.h>
 253
 254 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 255                         } while (0)
 256
 257 int
 258 main(int argc, char *argv[])
 259 {
 260     int loopctlfd, loopfd, backingfile;
 261     long devnr;
 262     char loopname[4096];
 263
 264     if (argc != 2) {
 265         fprintf(stderr, "Usage: %s backing\-file\en", argv[0]);
 266         exit(EXIT_FAILURE);
 267     }
 268
 269     loopctlfd = open("/dev/loop\-control", O_RDWR);
 270     if (loopctlfd == \-1)
 271         errExit("open: /dev/loop\-control");
 272
 273     devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
 274     if (devnr == \-1)
 275         errExit("ioctl\-LOOP_CTL_GET_FREE");
 276
 277     sprintf(loopname, "/dev/loop%ld", devnr);
 278     printf("loopname = %s\en", loopname);
 279
 280     loopfd = open(loopname, O_RDWR);
 281     if (loopfd == \-1)
 282         errExit("open: loopname");
 283
 284     backingfile = open(argv[1], O_RDWR);
 285     if (backingfile == \-1)
 286         errExit("open: backing\-file");
 287
 288     if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1)
 289         errExit("ioctl\-LOOP_SET_FD");
 290
 291     exit(EXIT_SUCCESS);
 292 }
 293 .EE
 294 .SH SEE ALSO
 295 .BR losetup (8),
 296 .BR mount (8)