loop-control(4) — Linux manual page


LOOP(4)                   Linux Programmer's Manual                  LOOP(4)

NAME         top

       loop, loop-control - loop devices

SYNOPSIS         top

       #include <linux/loop.h>

DESCRIPTION         top

       The loop device is a block device that maps its data blocks not to a
       physical device such as a hard disk or optical disk drive, but to the
       blocks of a regular file in a filesystem or to another block device.
       This can be useful for example to provide a block device for a
       filesystem image stored in a file, so that it can be mounted with the
       mount(8) command.  You could do

           $ dd if=/dev/zero of=file.img bs=1MiB count=10
           $ sudo losetup /dev/loop4 file.img
           $ sudo mkfs -t ext4 /dev/loop4
           $ sudo mkdir /myloopdev
           $ sudo mount /dev/loop4 /myloopdev

       See losetup(8) for another example.

       A transfer function can be specified for each loop device for encryp‐
       tion and decryption purposes.

       The following ioctl(2) operations are provided by the loop block de‐

              Associate the loop device with the open file whose file de‐
              scriptor is passed as the (third) ioctl(2) argument.

              Disassociate the loop device from any file descriptor.

              Set the status of the loop device using the (third) ioctl(2)
              argument.  This argument is a pointer to a loop_info struc‐
              ture, defined in <linux/loop.h> as:

                  struct loop_info {
                      int           lo_number;      /* ioctl r/o */
                      dev_t         lo_device;      /* ioctl r/o */
                      unsigned long lo_inode;       /* ioctl r/o */
                      dev_t         lo_rdevice;     /* ioctl r/o */
                      int           lo_offset;
                      int           lo_encrypt_type;
                      int           lo_encrypt_key_size;  /* ioctl w/o */
                      int           lo_flags;       /* ioctl r/w (r/o before
                                                       Linux 2.6.25) */
                      char          lo_name[LO_NAME_SIZE];
                      unsigned char lo_encrypt_key[LO_KEY_SIZE];
                                                    /* ioctl w/o */
                      unsigned long lo_init[2];
                      char          reserved[4];

              The encryption type (lo_encrypt_type) should be one of
              LO_CRYPT_DUMMY, LO_CRYPT_SKIPJACK, or (since Linux 2.6.0)

              The lo_flags field is a bit mask that can include zero or more
              of the following:

                     The loopback device is read-only.

              LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
                     The loopback device will autodestruct on last close.

              LO_FLAGS_PARTSCAN (since Linux 3.2)
                     Allow automatic partition scanning.

              LO_FLAGS_DIRECT_IO (since Linux 4.10)
                     Use direct I/O mode to access the backing file.

              The only lo_flags that can be modified by LOOP_SET_STATUS are

              Get the status of the loop device.  The (third) ioctl(2) argu‐
              ment must be a pointer to a struct loop_info.

       LOOP_CHANGE_FD (since Linux 2.6.5)
              Switch the backing store of the loop device to the new file
              identified file descriptor specified in the (third) ioctl(2)
              argument, which is an integer.  This operation is possible
              only if the loop device is read-only and the new backing store
              is the same size and type as the old backing store.

       LOOP_SET_CAPACITY (since Linux 2.6.30)
              Resize a live loop device.  One can change the size of the un‐
              derlying backing store and then use this operation so that the
              loop driver learns about the new size.  This operation takes
              no argument.

       LOOP_SET_DIRECT_IO (since Linux 4.10)
              Set DIRECT I/O mode on the loop device, so that it can be used
              to open backing file.  The (third) ioctl(2) argument is an un‐
              signed long value.  A nonzero represents direct I/O mode.

       LOOP_SET_BLOCK_SIZE (since Linux 4.14)
              Set the block size of the loop device.  The (third) ioctl(2)
              argument is an unsigned long value.  This value must be a
              power of two in the range [512,pagesize]; otherwise, an EINVAL
              error results.

       LOOP_CONFIGURE (since Linux 5.8)
              Setup and configure all loop device parameters in a single
              step using the (third) ioctl(2) argument.  This argument is a
              pointer to a loop_config structure, defined in <linux/loop.h>

                  struct loop_config {
                      __u32               fd;
                      __u32               block_size;
                      struct loop_info64  info;
                      __u64               __reserved[8];

              In addition to doing what LOOP_SET_STATUS can do, LOOP_CONFIG‐
              URE can also be used to do the following:

              * set the correct block size immediately by setting loop_con‐

              * explicitly request direct I/O mode by setting LO_FLAGS_DI‐
                RECT_IO in loop_config.info.lo_flags; and

              * explicitly request read-only mode by setting
                LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.

       Since Linux 2.6, there are two new ioctl(2) operations:

              These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS de‐
              scribed above but use the loop_info64 structure, which has
              some additional fields and a larger range for some other

                  struct loop_info64 {
                      uint64_t lo_device;           /* ioctl r/o */
                      uint64_t lo_inode;            /* ioctl r/o */
                      uint64_t lo_rdevice;          /* ioctl r/o */
                      uint64_t lo_offset;
                      uint64_t lo_sizelimit;  /* bytes, 0 == max available */
                      uint32_t lo_number;           /* ioctl r/o */
                      uint32_t lo_encrypt_type;
                      uint32_t lo_encrypt_key_size; /* ioctl w/o */
                      uint32_t lo_flags; i          /* ioctl r/w (r/o before
                                                       Linux 2.6.25) */
                      uint8_t  lo_file_name[LO_NAME_SIZE];
                      uint8_t  lo_crypt_name[LO_NAME_SIZE];
                      uint8_t  lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
                      uint64_t lo_init[2];

       Since Linux 3.1, the kernel provides the /dev/loop-control device,
       which permits an application to dynamically find a free device, and
       to add and remove loop devices from the system.  To perform these op‐
       erations, one first opens /dev/loop-control and then employs one of
       the following ioctl(2) operations:

              Allocate or find a free loop device for use.  On success, the
              device number is returned as the result of the call.  This op‐
              eration takes no argument.

              Add the new loop device whose device number is specified as a
              long integer in the third ioctl(2) argument.  On success, the
              device index is returned as the result of the call.  If the
              device is already allocated, the call fails with the error

              Remove the loop device whose device number is specified as a
              long integer in the third ioctl(2) argument.  On success, the
              device number is returned as the result of the call.  If the
              device is in use, the call fails with the error EBUSY.

FILES         top

              The loop block special device files.

EXAMPLES         top

       The program below uses the /dev/loop-control device to find a free
       loop device, opens the loop device, opens a file to be used as the
       underlying storage for the device, and then associates the loop
       device with the backing store.  The following shell session
       demonstrates the use of the program:

           $ dd if=/dev/zero of=file.img bs=1MiB count=10
           10+0 records in
           10+0 records out
           10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
           $ sudo ./mnt_loop file.img
           loopname = /dev/loop5

   Program source

       #include <fcntl.h>
       #include <linux/loop.h>
       #include <sys/ioctl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                               } while (0)

       main(int argc, char *argv[])
           int loopctlfd, loopfd, backingfile;
           long devnr;
           char loopname[4096];

           if (argc != 2) {
               fprintf(stderr, "Usage: %s backing-file\n", argv[0]);

           loopctlfd = open("/dev/loop-control", O_RDWR);
           if (loopctlfd == -1)
               errExit("open: /dev/loop-control");

           devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
           if (devnr == -1)

           sprintf(loopname, "/dev/loop%ld", devnr);
           printf("loopname = %s\n", loopname);

           loopfd = open(loopname, O_RDWR);
           if (loopfd == -1)
               errExit("open: loopname");

           backingfile = open(argv[1], O_RDWR);
           if (backingfile == -1)
               errExit("open: backing-file");

           if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)


SEE ALSO         top

       losetup(8), mount(8)

COLOPHON         top

       This page is part of release 5.09 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at

Linux                            2020-11-01                          LOOP(4)