Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

losetup

Set up and control loop devices.

Synopsis

losetup [loopdev]                           # show status of one device
losetup [-a] [-l]                           # list all used devices
losetup -f [--show] [-o offset] [file]      # find free device (optionally set up)
losetup [-o offset] [--sizelimit N] loopdev file  # set up loop device
losetup -d loopdev...                       # detach one or more devices
losetup -D                                  # detach all devices
losetup -j file                             # find devices associated with file
losetup -c loopdev                          # resize (reread backing file size)

Operation modes

List / query

  • No arguments or -a: Lists all active loop devices.
  • loopdev only: Shows info for a single device via LOOP_GET_STATUS64.
  • -j file: Finds all loop devices backed by the given file (scans sysfs).

Setup

  • loopdev file: Associates the loop device with the backing file.
  • -f file: Finds a free loop device via LOOP_CTL_GET_FREE, then sets it up.
  • Uses LOOP_SET_FD to associate, then LOOP_SET_STATUS64 to configure offset/sizelimit/flags.

Detach

  • -d loopdev...: Detaches one or more devices via LOOP_CLR_FD.
  • -D: Detaches all active loop devices.

Resize

  • -c loopdev: Tells the kernel to reread the backing file size via LOOP_SET_CAPACITY.

Inputs

SourcePurpose
/dev/loop-controlLOOP_CTL_GET_FREE ioctl to find free devices
/dev/loopNIoctls to set up, query, detach, resize
/sys/block/loopN/loop/backing_fileRead backing file path for listing
/sys/block/loopN/loop/offsetRead offset for listing
/sys/block/loopN/loop/sizelimitRead size limit for listing
/sys/block/loopN/loop/autoclearRead autoclear flag
/sys/block/loopN/loop/partscanRead partscan flag
/sys/block/loopN/loop/dioRead direct-io flag
/sys/block/loopN/roRead read-only status

Outputs

  • stdout: Device info in various formats (old-style -a, tabular --list)
  • /dev/loopN: Created/configured/detached via ioctls

Ioctls

IoctlValueTargetDescription
LOOP_SET_FD0x4C00/dev/loopNAssociate with backing file fd
LOOP_CLR_FD0x4C01/dev/loopNDetach (disassociate)
LOOP_SET_STATUS640x4C04/dev/loopNSet offset, sizelimit, flags
LOOP_GET_STATUS640x4C05/dev/loopNGet current status
LOOP_SET_CAPACITY0x4C07/dev/loopNReread backing file size
LOOP_CTL_GET_FREE0x4C82/dev/loop-controlFind free loop device number

Data structure: loop_info64

lo_device:           u64  (backing device, read-only)
lo_inode:            u64  (backing inode, read-only)
lo_rdevice:          u64  (read-only)
lo_offset:           u64  (byte offset into backing file)
lo_sizelimit:        u64  (0 = use entire file)
lo_number:           u32  (device number, read-only)
lo_encrypt_type:     u32  (obsolete)
lo_encrypt_key_size: u32  (obsolete)
lo_flags:            u32  (LO_FLAGS_*)
lo_file_name:        [u8; 64]  (reference string)
lo_crypt_name:       [u8; 64]  (obsolete)
lo_encrypt_key:      [u8; 32]  (obsolete)
lo_init:             [u64; 2]  (reserved)

Flags

FlagValueDescription
LO_FLAGS_READ_ONLY1Read-only device
LO_FLAGS_AUTOCLEAR4Auto-destroy on last close
LO_FLAGS_PARTSCAN8Auto partition scanning
LO_FLAGS_DIRECT_IO16Direct I/O to backing file

Command-line options

OptionDescription
-a, --allList all used devices
-d, --detachDetach one or more devices
-D, --detach-allDetach all used devices
-f, --findFind first unused device
-c, --set-capacityResize loop device
-j, --associated <file>List devices associated with file
-o, --offset <N>Start at byte offset into file
--sizelimit <N>Limit device size in bytes
-b, --sector-size <N>Set logical sector size (512-pagesize, power of 2)
-P, --partscanForce kernel partition table scan
-r, --read-onlySet up read-only
--showPrint device name after setup (with -f)
-l, --listTabular list format
-n, --noheadingsSuppress headers in list output
-v, --verboseVerbose mode
-J, --jsonJSON output format
-h, --helpDisplay help
-V, --versionDisplay version

Exit codes

CodeMeaning
0Success
1Device not configured (query mode)
2Error determining device status

Permissions

Setting up, detaching, and resizing loop devices requires root or CAP_SYS_ADMIN. Listing via sysfs is available to any user.

Not yet implemented

  • --direct-io flag
  • --loop-ref reference string
  • --nooverlap (-L)
  • --output column selection
  • --output-all
  • --raw output format
  • JSON output (-J)
  • Size suffix parsing for offset/sizelimit
  • LOOP_CONFIGURE atomic setup (Linux 5.8+)