sys-utils/losetup.8

   1 .TH LOSETUP 8 "November 2015" "util-linux" "System Administration"
   2 .SH NAME
   3 losetup \- set up and control loop devices
   4 .SH SYNOPSIS
   5 .ad l
   6 Get info:
   7 .sp
   8 .in +5
   9 .B losetup
  10 .I loopdev
  11 .sp
  12 .B losetup -l
  13 .RB [ \-a ]
  14 .sp
  15 .B losetup -j
  16 .I file
  17 .RB [ \-o
  18 .IR offset ]
  19 .sp
  20 .in -5
  21 Detach a loop device:
  22 .sp
  23 .in +5
  24 .B "losetup \-d"
  25 .IR loopdev ...
  26 .sp
  27 .in -5
  28 Detach all associated loop devices:
  29 .sp
  30 .in +5
  31 .B "losetup \-D"
  32 .sp
  33 .in -5
  34 Print the name of the first unused loop device:
  35 .sp
  36 .in +5
  37 .B "losetup \-f"
  38 .sp
  39 .in -5
  40 Set up a loop device:
  41 .sp
  42 .in +5
  43 .B losetup
  44 .RB [ \-o
  45 .IR offset ]
  46 .RB [ \-\-sizelimit
  47 .IR size ]
  48 .in +8
  49 .RB [ \-Pr ]
  50 .RB [ \-\-show ]  " \-f" | \fIloopdev\fP
  51 .I file
  52 .sp
  53 .in -13
  54 Resize a loop device:
  55 .sp
  56 .in +5
  57 .B "losetup \-c"
  58 .I loopdev
  59 .in -5
  60 .ad b
  61 .SH DESCRIPTION
  62 .B losetup
  63 is used to associate loop devices with regular files or block devices,
  64 to detach loop devices, and to query the status of a loop device.  If only the
  65 \fIloopdev\fP argument is given, the status of the corresponding loop
  66 device is shown.  If no option is given, all loop devices are shown.
  67 .sp
  68 Note that the old output format (i.e. \fBlosetup -a\fR) with comma-delimited
  69 strings is deprecated in favour of the \fB--list\fR output format.
  70
  71 .SH OPTIONS
  72 The \fIsize\fR and \fIoffset\fR
  73 arguments may be followed by the multiplicative suffixes KiB (=1024),
  74 MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is
  75 optional, e.g., "K" has the same meaning as "KiB") or the suffixes
  76 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  77
  78 .TP
  79 .BR \-a , " \-\-all"
  80 Show the status of all loop devices.  Note that not all information is accessible
  81 for non-root users.  See also \fB\-\-list\fR.  The old output format (as printed
  82 without \fB--list)\fR is deprecated.
  83 .TP
  84 .BR \-c , " \-\-set\-capacity " \fIloopdev
  85 Force the loop driver to reread the size of the file associated with the
  86 specified loop device.
  87 .TP
  88 .BR \-d , " \-\-detach " \fIloopdev\fR...
  89 Detach the file or device associated with the specified loop device(s).
  90 .TP
  91 .BR \-D , " \-\-detach\-all"
  92 Detach all associated loop devices.
  93 .TP
  94 .BR \-\-direct\-io [ =on | off ]
  95 Enable or disable direct I/O for the backing file.  The optional argument
  96 can be either \fBon\fR or \fBoff\fR.  If the argument is omitted, it defaults
  97 to \fBon\fR.
  98 .TP
  99 .BR \-f , " \-\-find"
 100 Find the first unused loop device.  If a
 101 .I file
 102 argument is present, use the found device as loop device.
 103 Otherwise, just print its name.
 104 .TP
 105 .BR \-j , " \-\-associated " \fIfile
 106 Show the status of all loop devices associated with the given
 107 .IR file .
 108 .TP
 109 .BR \-J , " \-\-json"
 110 Use JSON format for \fB\-\-list\fP output.
 111 .TP
 112 .BR \-l , " \-\-list"
 113 If a loop device or the \fB-a\fR option is specified, print the default columns
 114 for either the specified loop device or all loop devices; the default is to
 115 print info about all devices.  See also \fB\-\-output\fP, \fB\-\-noheadings\fP
 116 \fB\-\-json\fP and \fB\-\-raw\fP.
 117 .TP
 118 .BR \-n , " \-\-noheadings"
 119 Don't print headings for \fB\-\-list\fP output format.
 120 .TP
 121 .BR \-o , " \-\-offset " \fIoffset
 122 The data start is moved \fIoffset\fP bytes into the specified file or device.
 123 .TP
 124 .BR \-O , " \-\-output " \fIcolumns
 125 Specify the columns that are to be printed for the \fB\-\-list\fP output.
 126 .TP
 127 .BR \-P , " \-\-partscan"
 128 Force the kernel to scan the partition table on a newly created loop device.
 129 .IP "\fB\-\-raw\fP"
 130 Use the raw \fB\-\-list\fP output format.
 131 .TP
 132 .BR \-r , " \-\-read\-only"
 133 Set up a read-only loop device.
 134 .IP "\fB\-\-sizelimit \fIsize\fP"
 135 The data end is set to no more than \fIsize\fP bytes after the data start.
 136 .IP "\fB\-\-show\fP"
 137 Display the name of the assigned loop device if the
 138 .B \-f
 139 option and a
 140 .I file
 141 argument are present.
 142 .TP
 143 .BR \-v , " \-\-verbose"
 144 Verbose mode.
 145 .TP
 146 .BR \-V , " \-\-version"
 147 Display version information and exit.
 148 .TP
 149 .BR \-h , " \-\-help"
 150 Display help text and exit.
 151
 152 .SH ENCRYPTION
 153 .B Cryptoloop is no longer supported in favor of dm-crypt.
 154 .B For more details see cryptsetup(8).
 155
 156 .SH RETURN VALUE
 157 .B losetup
 158 returns 0 on success, nonzero on failure.  When
 159 .B losetup
 160 displays the status of a loop device, it returns 1 if the device
 161 is not configured and 2 if an error occurred which prevented
 162 determining the status of the device.
 163
 164 .SH FILES
 165 .TP
 166 .I /dev/loop[0..N]
 167 loop block devices
 168 .TP
 169 .I /dev/loop-control
 170 loop control device
 171
 172 .SH EXAMPLE
 173 The following commands can be used as an example of using the loop device.
 174 .nf
 175 .IP
 176 # dd if=/dev/zero of=~/file.img bs=1MiB count=10
 177 # losetup --find --show ~/file.img
 178 /dev/loop0
 179 # mkfs -t ext2 /dev/loop0
 180 # mount /dev/loop0 /mnt
 181  ...
 182 # umount /dev/loop0
 183 # losetup --detach /dev/loop0
 184 .fi
 185 .SH ENVIRONMENT
 186 .IP LOOPDEV_DEBUG=all
 187 enables debug output.
 188 .SH AUTHORS
 189 Karel Zak <kzak@redhat.com>, based on the original version from
 190 Theodore Ts'o <tytso@athena.mit.edu>
 191 .SH AVAILABILITY
 192 The losetup command is part of the util-linux package and is available from
 193 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.