{
    "mode": "man",
    "parameter": "LOOP",
    "section": "4",
    "url": "https://www.chedong.com/phpMan.php/man/LOOP/4/json",
    "generated": "2026-05-30T09:07:44Z",
    "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, LOOPGETSTATUS64\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",
            "subsections": []
        },
        "COLOPHON": {
            "content": "This  page  is  part  of  release  5.10 of the Linux man-pages project.  A description of the\nproject, information about reporting bugs, and the latest version of this page, can be  found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux                                        2020-11-01                                      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"
        }
    ]
}