# loop-control - loop devices - man(4) - [phpMan] [_loop_(4)](https://www.chedong.com/phpMan.php/man/loop/4/markdown) Kernel Interfaces Manual [_loop_(4)](https://www.chedong.com/phpMan.php/man/loop/4/markdown) ## NAME loop, loop-control - loop devices ## SYNOPSIS #include ## DESCRIPTION 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)](https://www.chedong.com/phpMan.php/man/mount/8/markdown) 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)](https://www.chedong.com/phpMan.php/man/losetup/8/markdown) for another example. A transfer function can be specified for each loop device for encryption and decryption pur‐ poses. The following [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) operations are provided by the loop block device: **LOOP_SET_FD** Associate the loop device with the open file whose file descriptor is passed as the (third) [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) argument. **LOOP_CLR_FD** Disassociate the loop device from any file descriptor. **LOOP_SET_STATUS** Set the status of the loop device using the (third) [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) argument. This argument is a pointer to a _loop_info_ structure, defined in __ 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_NONE**, **LO_CRYPT_XOR**, **LO_CRYPT_DES**, **LO_CRYPT_FISH2**, **LO_CRYPT_BLOW**, **LO_CRYPT_CAST128**, **LO_CRYPT_IDEA**, **LO_CRYPT_DUMMY**, **LO_CRYPT_SKIPJACK**, or (since Linux 2.6.0) **LO_CRYPT_CRYPTOAPI**. The _lo_flags_ field is a bit mask that can include zero or more of the following: **LO_FLAGS_READ_ONLY** 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 **LO_FLAGS_AUTOCLEAR **and **LO_FLAGS_PARTSCAN**. **LOOP_GET_STATUS** Get the status of the loop device. The (third) [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) argument 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)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) 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 underlying 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)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) argument is an unsigned 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)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) 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)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) argument. This argument is a pointer to a _loop_config_ structure, defined in __ as: 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_CONFIGURE **can also be used to do the following: • set the correct block size immediately by setting _loop_config.block_size_; • explicitly request direct I/O mode by setting **LO_FLAGS_DIRECT_IO **in _loop_con‐_ _fig.info.lo_flags_; and • explicitly request read-only mode by setting **LO_FLAGS_READ_ONLY **in _loop_con‐_ _fig.info.lo_flags_. Since Linux 2.6, there are two new [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) operations: **LOOP_SET_STATUS64** **LOOP_GET_STATUS64** These are similar to **LOOP_SET_STATUS **and **LOOP_GET_STATUS **described above but use the _loop_info64_ structure, which has some additional fields and a larger range for some other fields: 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]; }; ### /dev/loop-control Since Linux 3.1, the kernel provides the _/dev/loop-control_ device, which permits an applica‐ tion to dynamically find a free device, and to add and remove loop devices from the system. To perform these operations, one first opens _/dev/loop-control_ and then employs one of the following [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) operations: **LOOP_CTL_GET_FREE** Allocate or find a free loop device for use. On success, the device number is re‐ turned as the result of the call. This operation takes no argument. **LOOP_CTL_ADD** Add the new loop device whose device number is specified as a long integer in the third [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) 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 **EEXIST**. **LOOP_CTL_REMOVE** Remove the loop device whose device number is specified as a long integer in the third [**ioctl**(2)](https://www.chedong.com/phpMan.php/man/ioctl/2/markdown) 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 _/dev/loop*_ The loop block special device files. ## EXAMPLES 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 asso‐ ciates 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 #include #include #include #include #include #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \ } while (0) int 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]); exit(EXIT_FAILURE); } 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) errExit("ioctl-LOOP_CTL_GET_FREE"); 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) errExit("ioctl-LOOP_SET_FD"); exit(EXIT_SUCCESS); } ## SEE ALSO [**losetup**(8)](https://www.chedong.com/phpMan.php/man/losetup/8/markdown), [**mount**(8)](https://www.chedong.com/phpMan.php/man/mount/8/markdown) Linux man-pages 6.7 2023-10-31 [_loop_(4)](https://www.chedong.com/phpMan.php/man/loop/4/markdown)