{
    "mode": "man",
    "parameter": "loop-control",
    "section": "4",
    "url": "https://www.chedong.com/phpMan.php/man/loop-control/4/json",
    "generated": "2026-10-07T13:51:22Z",
    "synopsis": "#include <linux/loop.h>",
    "sections": {
        "NAME": {
            "content": "loop, loop-control - loop devices\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "#include <linux/loop.h>\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The  loop device is a block device that maps its data blocks not to a physical device such as\na hard disk or optical disk drive, but to the blocks of a regular file in a filesystem or  to\nanother  block  device.   This  can  be  useful  for  example to provide a block device for a\nfilesystem image stored in a file, so that it can be mounted with the mount(8) command.   You\ncould do\n\n$ dd if=/dev/zero of=file.img bs=1MiB count=10\n$ sudo losetup /dev/loop4 file.img\n$ sudo mkfs -t ext4 /dev/loop4\n$ sudo mkdir /myloopdev\n$ sudo mount /dev/loop4 /myloopdev\n\nSee losetup(8) for another example.\n\nA  transfer function can be specified for each loop device for encryption and decryption pur‐\nposes.\n\nThe following ioctl(2) operations are provided by the loop block device:\n\nLOOPSETFD\nAssociate the loop device with the open file whose file descriptor is  passed  as  the\n(third) ioctl(2) argument.\n\nLOOPCLRFD\nDisassociate the loop device from any file descriptor.\n\nLOOPSETSTATUS\nSet  the status of the loop device using the (third) ioctl(2) argument.  This argument\nis a pointer to a loopinfo structure, defined in <linux/loop.h> as:\n\nstruct loopinfo {\nint           lonumber;      /* ioctl r/o */\ndevt         lodevice;      /* ioctl r/o */\nunsigned long loinode;       /* ioctl r/o */\ndevt         lordevice;     /* ioctl r/o */\nint           looffset;\nint           loencrypttype;\nint           loencryptkeysize;  /* ioctl w/o */\nint           loflags;       /* ioctl r/w (r/o before\nLinux 2.6.25) */\nchar          loname[LONAMESIZE];\nunsigned char loencryptkey[LOKEYSIZE];\n/* ioctl w/o */\nunsigned long loinit[2];\nchar          reserved[4];\n};\n\nThe encryption type (loencrypttype) should be one  of  LOCRYPTNONE,  LOCRYPTXOR,\nLOCRYPTDES,    LOCRYPTFISH2,   LOCRYPTBLOW,   LOCRYPTCAST128,   LOCRYPTIDEA,\nLOCRYPTDUMMY, LOCRYPTSKIPJACK, or (since Linux 2.6.0) LOCRYPTCRYPTOAPI.\n\nThe loflags field is a bit mask that can include zero or more of the following:\n\nLOFLAGSREADONLY\nThe loopback device is read-only.\n\nLOFLAGSAUTOCLEAR (since Linux 2.6.25)\nThe loopback device will autodestruct on last close.\n\nLOFLAGSPARTSCAN (since Linux 3.2)\nAllow automatic partition scanning.\n\nLOFLAGSDIRECTIO (since Linux 4.10)\nUse direct I/O mode to access the backing file.\n\nThe only loflags that can be modified by LOOPSETSTATUS are  LOFLAGSAUTOCLEAR  and\nLOFLAGSPARTSCAN.\n\nLOOPGETSTATUS\nGet the status of the loop device.  The (third) ioctl(2) argument must be a pointer to\na struct loopinfo.\n\nLOOPCHANGEFD (since Linux 2.6.5)\nSwitch the backing store of the loop device to the new file identified file descriptor\nspecified  in  the  (third) ioctl(2) argument, which is an integer.  This operation is\npossible only if the loop device is read-only and the new backing store  is  the  same\nsize and type as the old backing store.\n\nLOOPSETCAPACITY (since Linux 2.6.30)\nResize  a  live  loop device.  One can change the size of the underlying backing store\nand then use this operation so that the loop driver learns about the new  size.   This\noperation takes no argument.\n\nLOOPSETDIRECTIO (since Linux 4.10)\nSet  DIRECT  I/O mode on the loop device, so that it can be used to open backing file.\nThe (third) ioctl(2) argument is an unsigned long value.  A nonzero represents  direct\nI/O mode.\n\nLOOPSETBLOCKSIZE (since Linux 4.14)\nSet  the  block size of the loop device.  The (third) ioctl(2) argument is an unsigned\nlong value.  This value must be a power of two in the range [512,pagesize]; otherwise,\nan EINVAL error results.\n\nLOOPCONFIGURE (since Linux 5.8)\nSetup and configure all loop device parameters in a  single  step  using  the  (third)\nioctl(2)  argument.  This argument is a pointer to a loopconfig structure, defined in\n<linux/loop.h> as:\n\nstruct loopconfig {\nu32               fd;\nu32               blocksize;\nstruct loopinfo64  info;\nu64               reserved[8];\n};\n\nIn addition to doing what LOOPSETSTATUS can do, LOOPCONFIGURE can also be  used  to\ndo the following:\n\n•  set the correct block size immediately by setting loopconfig.blocksize;\n\n•  explicitly  request  direct  I/O  mode  by  setting LOFLAGSDIRECTIO in loopcon‐\nfig.info.loflags; and\n\n•  explicitly request  read-only  mode  by  setting  LOFLAGSREADONLY  in  loopcon‐\nfig.info.loflags.\n\nSince Linux 2.6, there are two new ioctl(2) operations:\n\nLOOPSETSTATUS64\nLOOPGETSTATUS64\nThese  are  similar to LOOPSETSTATUS and LOOPGETSTATUS described above but use the\nloopinfo64 structure, which has some additional fields and a larger  range  for  some\nother fields:\n\nstruct loopinfo64 {\nuint64t lodevice;           /* ioctl r/o */\nuint64t loinode;            /* ioctl r/o */\nuint64t lordevice;          /* ioctl r/o */\nuint64t looffset;\nuint64t losizelimit;  /* bytes, 0 == max available */\nuint32t lonumber;           /* ioctl r/o */\nuint32t loencrypttype;\nuint32t loencryptkeysize; /* ioctl w/o */\nuint32t loflags; i          /* ioctl r/w (r/o before\nLinux 2.6.25) */\nuint8t  lofilename[LONAMESIZE];\nuint8t  locryptname[LONAMESIZE];\nuint8t  loencryptkey[LOKEYSIZE]; /* ioctl w/o */\nuint64t loinit[2];\n};\n",
            "subsections": [
                {
                    "name": "/dev/loop-control",
                    "content": "Since  Linux 3.1, the kernel provides the /dev/loop-control device, which permits an applica‐\ntion to dynamically find a free device, and to add and remove loop devices from  the  system.\nTo  perform  these  operations, one first opens /dev/loop-control and then employs one of the\nfollowing ioctl(2) operations:\n\nLOOPCTLGETFREE\nAllocate or find a free loop device for use.  On success, the  device  number  is  re‐\nturned as the result of the call.  This operation takes no argument.\n\nLOOPCTLADD\nAdd  the  new  loop  device  whose device number is specified as a long integer in the\nthird ioctl(2) argument.  On success, the device index is returned as  the  result  of\nthe call.  If the device is already allocated, the call fails with the error EEXIST.\n\nLOOPCTLREMOVE\nRemove the loop device whose device number is specified as a long integer in the third\nioctl(2)  argument.   On  success,  the device number is returned as the result of the\ncall.  If the device is in use, the call fails with the error EBUSY.\n"
                }
            ]
        },
        "FILES": {
            "content": "/dev/loop*\nThe loop block special device files.\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "The program below uses the /dev/loop-control device to find a free  loop  device,  opens  the\nloop device, opens a file to be used as the underlying storage for the device, and then asso‐\nciates  the loop device with the backing store.  The following shell session demonstrates the\nuse of the program:\n\n$ dd if=/dev/zero of=file.img bs=1MiB count=10\n10+0 records in\n10+0 records out\n10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s\n$ sudo ./mntloop file.img\nloopname = /dev/loop5\n",
            "subsections": [
                {
                    "name": "Program source",
                    "content": "#include <fcntl.h>\n#include <linux/loop.h>\n#include <sys/ioctl.h>\n#include <stdio.h>\n#include <stdlib.h>\n#include <unistd.h>\n\n#define errExit(msg)    do { perror(msg); exit(EXITFAILURE); \\\n} while (0)\n\nint\nmain(int argc, char *argv[])\n{\nint loopctlfd, loopfd, backingfile;\nlong devnr;\nchar loopname[4096];\n\nif (argc != 2) {\nfprintf(stderr, \"Usage: %s backing-file\\n\", argv[0]);\nexit(EXITFAILURE);\n}\n\nloopctlfd = open(\"/dev/loop-control\", ORDWR);\nif (loopctlfd == -1)\nerrExit(\"open: /dev/loop-control\");\n\ndevnr = ioctl(loopctlfd, LOOPCTLGETFREE);\nif (devnr == -1)\nerrExit(\"ioctl-LOOPCTLGETFREE\");\n\nsprintf(loopname, \"/dev/loop%ld\", devnr);\nprintf(\"loopname = %s\\n\", loopname);\n\nloopfd = open(loopname, ORDWR);\nif (loopfd == -1)\nerrExit(\"open: loopname\");\n\nbackingfile = open(argv[1], ORDWR);\nif (backingfile == -1)\nerrExit(\"open: backing-file\");\n\nif (ioctl(loopfd, LOOPSETFD, backingfile) == -1)\nerrExit(\"ioctl-LOOPSETFD\");\n\nexit(EXITSUCCESS);\n}\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "losetup(8), mount(8)\n\nLinux man-pages 6.7                          2023-10-31                                      loop(4)",
            "subsections": []
        }
    },
    "summary": "loop, loop-control - loop devices",
    "flags": [],
    "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 ./mntloop file.img",
        "loopname = /dev/loop5",
        "#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(EXITFAILURE); \\",
        "} 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(EXITFAILURE);",
        "loopctlfd = open(\"/dev/loop-control\", ORDWR);",
        "if (loopctlfd == -1)",
        "errExit(\"open: /dev/loop-control\");",
        "devnr = ioctl(loopctlfd, LOOPCTLGETFREE);",
        "if (devnr == -1)",
        "errExit(\"ioctl-LOOPCTLGETFREE\");",
        "sprintf(loopname, \"/dev/loop%ld\", devnr);",
        "printf(\"loopname = %s\\n\", loopname);",
        "loopfd = open(loopname, ORDWR);",
        "if (loopfd == -1)",
        "errExit(\"open: loopname\");",
        "backingfile = open(argv[1], ORDWR);",
        "if (backingfile == -1)",
        "errExit(\"open: backing-file\");",
        "if (ioctl(loopfd, LOOPSETFD, backingfile) == -1)",
        "errExit(\"ioctl-LOOPSETFD\");",
        "exit(EXITSUCCESS);"
    ],
    "see_also": [
        {
            "name": "losetup",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/losetup/8/json"
        },
        {
            "name": "mount",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/mount/8/json"
        }
    ]
}