loop(4)

🌸 LOOP(4) 🌸 — loop devices, but make it a whole vibe

ok bestie, sit down, hydrate, because today we're talking about loop, loop-control and honestly? it's giving main character energy in the kernel interface world. 💅

---

✨ NAME ✨

loop, loop-control — loop devices 🌀

---

✨ SYNOPSIS ✨

#include <linux/loop.h>

periodt. that's the whole synopsis. slay. ✨

---

✨ DESCRIPTION ✨

so. the loop device is a block device and here's the twist — it doesn't map its data blocks to a physical device like a hard disk or an optical disk drive (no cap, zero hardware vibes) ✨. instead it maps them to the blocks of a regular file sitting in a filesystem, or to another block device. iconic behavior honestly.

and bestie, why do you care? because this lets you hand a filesystem image stored in a file its very own block device so you can mount it with the mount(8) command. it's giving "file, but make it a disk." 🫶

you could literally 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;

and boom. you're in. 💖 (go check losetup(8) for another example btw, they ate too.)

also — a transfer function can be specified for each loop device, for encryption and decryption purposes. so yes, the loop device can keep a secret. 🤫

the following ioctl(2) 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) argument. like "hey loop, this file? yours now." 💞
• LOOP_CLR_FD — disassociate the loop device from any file descriptor. it's the breakup. no hard feelings. 🥀
• LOOP_SET_STATUS — set the status of the loop device using the (third) ioctl(2) argument. that argument is a pointer to a loop_info structure, 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_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. yes that's a lot, no you don't need to memorize them all, just know they exist bestie. 📝

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. look but don't touch energy. 👀
• LO_FLAGS_AUTOCLEAR (since Linux 2.6.25) — the loopback device will autodestruct on last close. it's giving self-destructing mission. 💥
• 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. 🚀

also important: the only lo_flags that can be modified by LOOP_SET_STATUS are LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN. the rest are just there to look pretty. periodt. 💅

• LOOP_GET_STATUS — get the status of the loop device. the (third) ioctl(2) argument must be a pointer to a struct loop_info. it's the "wyd loop" text of ioctls. 📱
• 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. okay but the tea ☕ is that 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. strict. no exceptions. 💀
• LOOP_SET_CAPACITY (since Linux 2.6.30) — resize a live loop device. you can change the size of the underlying backing store and then use this operation so that the loop driver learns about the new size. glow-up, but for storage. ✨ 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 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) argument is an unsigned long value. this value must be a power of two in the range [512,pagesize]; otherwise, an EINVAL error results. math is mathing, respect the range bestie. 😤
• 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> 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_config.info.lo_flags; and
• explicitly request read-only mode by setting LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.

one ioctl, all the settings? that's efficiency core. ate. 👑

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

• LOOP_SET_STATUS64
• LOOP_GET_STATUS64

these are similar to LOOP_SET_STATUS and LOOP_GET_STATUS described above ✨ but they 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];
};

64-bit edition. bigger, bolder, more fields. the upgrade arc we deserved. 🌈

---

✨ /dev/loop-control ✨

since Linux 3.1, the kernel provides the /dev/loop-control device, and bestie?? it permits an application to dynamically find a free device, and to add and remove loop devices from the system. so much freedom. 🦋

to perform these operations, you first open /dev/loop-control and then employ one of the following ioctl(2) operations:

• LOOP_CTL_GET_FREE — allocate or find a free loop device for use. on success, the device number is returned as the result of the call. this operation takes no argument. free real estate!! 🏠
• LOOP_CTL_ADD — 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 EEXIST. sorry babe, taken. 🙈
• LOOP_CTL_REMOVE — 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. it's busy, it'll text you back. 🫠

---

✨ FILES ✨

• /dev/loop* — the loop block special device files. the whole squad. 👯

---

✨ 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 associates the loop device with the backing store. it's giving full journey, beginning to end. 🎬

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

look at that throughput. 1.7 GB/s. we love to see it. ⚡

✨ Program source ✨

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

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)
        err(EXIT_FAILURE, "open: /dev/loop-control");

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

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

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

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

    if (ioctl(loopfd, LOOP_SET_FD, backingfile) == -1)
        err(EXIT_FAILURE, "ioctl-LOOP_SET_FD");

    exit(EXIT_SUCCESS);
}

copy it, compile it, live your truth. 💖

---

✨ SEE ALSO ✨

losetup(8), mount(8) — go read them too, they're the supporting cast and they understood the assignment. 📚

---

aaaand that's the whole page bestie!! 🎀 this one came from Linux man-pages 6.20, dated 2026-02-08, and yeah — that's the loop(4) manual page, wrapped and delivered with love. now go loop something. i believe in you. 💜✨🦋