1LOSETUP(8)                   System Administration                  LOSETUP(8)
2
3
4

NAME

6       losetup - set up and control loop devices
7

SYNOPSIS

9       Get info:
10
11            losetup [loopdev]
12
13            losetup -l [-a]
14
15            losetup -j file [-o offset]
16
17       Detach a loop device:
18
19            losetup -d loopdev...
20
21       Detach all associated loop devices:
22
23            losetup -D
24
25       Set up a loop device:
26
27            losetup [-o offset] [--sizelimit size] [--sector-size size]
28                    [-Pr] [--show] -f|loopdev file
29
30       Resize a loop device:
31
32            losetup -c loopdev
33

DESCRIPTION

35       losetup  is  used to associate loop devices with regular files or block
36       devices, to detach loop devices, and to query  the  status  of  a  loop
37       device.   If only the loopdev argument is given, the status of the cor‐
38       responding loop device is shown.  If  no  option  is  given,  all  loop
39       devices are shown.
40
41       Note that the old output format (i.e., losetup -a) with comma-delimited
42       strings is deprecated in favour of the --list output format.
43
44       It's possible to create more independent  loop  devices  for  the  same
45       backing  file.   This setup may be dangerous, can cause data loss, cor‐
46       ruption and overwrites.  Use --nooverlap with --find  during  setup  to
47       avoid this problem.
48
49

OPTIONS

51       The  size  and  offset  arguments may be followed by the multiplicative
52       suffixes KiB (=1024), MiB (=1024*1024), and so on for  GiB,  TiB,  PiB,
53       EiB,  ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning
54       as "KiB") or the suffixes KB (=1000), MB (=1000*1000), and  so  on  for
55       GB, TB, PB, EB, ZB and YB.
56
57
58       -a, --all
59              Show the status of all loop devices.  Note that not all informa‐
60              tion is accessible for non-root users.  See  also  --list.   The
61              old output format (as printed without --list) is deprecated.
62
63       -d, --detach loopdev...
64              Detach  the  file  or  device associated with the specified loop
65              device(s). Note that since Linux v3.7 kernel uses  "lazy  device
66              destruction".   The detach operation does not return EBUSY error
67              anymore if device is actively used by system, but it  is  marked
68              by autoclear flag and destroyed later.
69
70       -D, --detach-all
71              Detach all associated loop devices.
72
73       -f, --find [file]
74              Find  the  first  unused  loop  device.   If  a file argument is
75              present, use the found device as loop device.   Otherwise,  just
76              print its name.
77
78       --show Display  the  name  of the assigned loop device if the -f option
79              and a file argument are present.
80
81       -L, --nooverlap
82              Check for conflicts between loop devices to avoid situation when
83              the  same  backing  file is shared between more loop devices. If
84              the file is already used  by  another  device  then  re-use  the
85              device  rather  than a new one. The option makes sense only with
86              --find.
87
88       -j, --associated file [-o offset]
89              Show the status of all loop devices associated  with  the  given
90              file.
91
92       -o, --offset offset
93              The  data start is moved offset bytes into the specified file or
94              device.  The offset may be followed by the  multiplicative  suf‐
95              fixes; see above.
96
97       --sizelimit size
98              The  data  end  is set to no more than size bytes after the data
99              start.  The size may be followed by the multiplicative suffixes;
100              see above.
101
102       -b, --sector-size size
103              Set  the  logical sector size of the loop device in bytes (since
104              Linux 4.14). The option may be  used  when  create  a  new  loop
105              device  as  well as stand-alone command to modify sector size of
106              the already existing loop device.
107
108       -c, --set-capacity loopdev
109              Force the loop driver to reread the size of the file  associated
110              with the specified loop device.
111
112       -P, --partscan
113              Force  the kernel to scan the partition table on a newly created
114              loop device.  Note that the partition table parsing  depends  on
115              sector  sizes.   The default is sector size is 512 bytes, other‐
116              wise you need to use  the  option  --sector-size  together  with
117              --partscan.
118
119       -r, --read-only
120              Set up a read-only loop device.
121
122       --direct-io[=on|off]
123              Enable or disable direct I/O for the backing file.  The optional
124              argument can be either on or off.  If the argument  is  omitted,
125              it defaults to on.
126
127       -v, --verbose
128              Verbose mode.
129
130       -l, --list
131              If  a  loop  device  or  the  -a  option is specified, print the
132              default columns for either the specified loop device or all loop
133              devices;  the  default  is to print info about all devices.  See
134              also --output, --noheadings, --raw, and --json.
135
136       -O, --output column[,column]...
137              Specify the columns that are to be printed for the  --list  out‐
138              put.  Use --help to get a list of all supported columns.
139
140       --output-all
141              Output all available columns.
142
143       -n, --noheadings
144              Don't print headings for --list output format.
145
146       --raw  Use the raw --list output format.
147
148       -J, --json
149              Use JSON format for --list output.
150
151       -V, --version
152              Display version information and exit.
153
154       -h, --help
155              Display help text and exit.
156
157

ENCRYPTION

159       Cryptoloop  is  no  longer  supported  in  favor of dm-crypt.  For more
160       details see cryptsetup(8).
161
162

RETURN VALUE

164       losetup returns 0 on success, nonzero on failure.   When  losetup  dis‐
165       plays  the  status  of a loop device, it returns 1 if the device is not
166       configured and 2 if an error occurred which prevented  determining  the
167       status of the device.
168
169

FILES

171       /dev/loop[0..N]
172              loop block devices
173
174       /dev/loop-control
175              loop control device
176
177

EXAMPLE

179       The  following  commands  can  be  used as an example of using the loop
180       device.
181
182              # dd if=/dev/zero of=~/file.img bs=1024k count=10
183              # losetup --find --show ~/file.img
184              /dev/loop0
185              # mkfs -t ext2 /dev/loop0
186              # mount /dev/loop0 /mnt
187               ...
188              # umount /dev/loop0
189              # losetup --detach /dev/loop0
190

ENVIRONMENT

192       LOOPDEV_DEBUG=all
193              enables debug output.
194

AUTHORS

196       Karel  Zak  <kzak@redhat.com>,  based  on  the  original  version  from
197       Theodore Ts'o <tytso@athena.mit.edu>
198

AVAILABILITY

200       The  losetup command is part of the util-linux package and is available
201       from https://www.kernel.org/pub/linux/utils/util-linux/.
202
203
204
205util-linux                       November 2015                      LOSETUP(8)
Impressum