sys-utils/losetup.8

   1 .TH LOSETUP 8 "July 2003" "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 -a
  13 .sp
  14 .B losetup -j
  15 .I file
  16 .RB [ \-o
  17 .IR offset ]
  18 .sp
  19 .in -5
  20 Delete loop:
  21 .sp
  22 .in +5
  23 .B "losetup \-d"
  24 .IR loopdev ...
  25 .sp
  26 .in -5
  27 Delete all used loop devices:
  28 .sp
  29 .in +5
  30 .B "losetup \-D"
  31 .sp
  32 .in -5
  33 Print name of first unused loop device:
  34 .sp
  35 .in +5
  36 .B "losetup \-f"
  37 .sp
  38 .in -5
  39 Setup loop device:
  40 .sp
  41 .in +5
  42 .B losetup
  43 .RB [{ \-e | \-E }
  44 .IR encryption ]
  45 .RB [ \-o
  46 .IR offset ]
  47 .RB [ \-\-sizelimit
  48 .IR size ]
  49 .in +8
  50 .RB [ \-p
  51 .IR pfd ]
  52 .RB [ \-rP ]
  53 .RB { \-f [ \-\-show ]| \fIloopdev\fP }
  54 .I file
  55 .sp
  56 .in -13
  57 Resize loop device:
  58 .sp
  59 .in +5
  60 .B "losetup \-c"
  61 .I loopdev
  62 .in -5
  63 .ad b
  64 .SH DESCRIPTION
  65 .B losetup
  66 is used to associate loop devices with regular files or block devices,
  67 to detach loop devices and to query the status of a loop device. If only the
  68 \fIloopdev\fP argument is given, the status of the corresponding loop
  69 device is shown.
  70
  71 .SH OPTIONS
  72 +The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
  73 +suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
  74 +(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes
  75 +KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
  76
  77 .IP "\fB\-a, \-\-all\fP"
  78 show status of all loop devices. Note that not all information are accessible
  79 for non-root users.
  80 .IP "\fB\-c, \-\-set-capacity\fP \fIloopdev\fP
  81 force loop driver to reread size of the file associated with the specified loop device
  82 .IP "\fB\-d, \-\-detach\fP \fIloopdev\fP..."
  83 detach the file or device associated with the specified loop device(s)
  84 .IP "\fB\-D, \-\-detach-all\fP"
  85 detach all associated loop devices
  86 .IP "\fB\-e, \-E, \-\-encryption \fIencryption_type\fP"
  87 enable data encryption with specified name or number
  88 .IP "\fB\-f, \-\-find\fP"
  89 find the first unused loop device. If a
  90 .I file
  91 argument is present, use this device. Otherwise, print its name
  92 .IP "\fB\-h, \-\-help\fP"
  93 print help
  94 .IP "\fB\-j, \-\-associated \fIfile\fP"
  95 show status of all loop devices associated with given
  96 .I file
  97 .IP "\fB\-o, \-\-offset \fIoffset\fP"
  98 the data start is moved \fIoffset\fP bytes into the specified file or
  99 device
 100 .IP "\fB\-\-sizelimit \fIsize\fP"
 101 the data end is set to no more than \fIsize\fP bytes after the data start
 102 .IP "\fB\-p, \-\-pass-fd \fInum\fP"
 103 read the passphrase from file descriptor with number
 104 .I num
 105 instead of from the terminal
 106 .IP "\fB\-P, \-\-partscan\fP"
 107 force kernel to scan partition table on newly created loop device
 108 .IP "\fB\-r, \-\-read-only\fP"
 109 setup read-only loop device
 110 .IP "\fB\-\-show\fP"
 111 print device name if the
 112 .I -f
 113 option and a
 114 .I file
 115 argument are present.
 116 .IP "\fB\-v, \-\-verbose\fP"
 117 verbose mode
 118
 119 .SH ENCRYPTION
 120 .B Cryptoloop is deprecated in favor of dm-crypt. For more details see
 121 .B cryptsetup (8). It is possible that all bug reports regarding to -E/-e
 122 .B options will be ignored.
 123
 124
 125 It is possible to specify transfer functions (for encryption/decryption
 126 or other purposes) using one of the
 127 .B \-E
 128 and
 129 .B \-e
 130 options.
 131 There are two mechanisms to specify the desired encryption: by number
 132 and by name. If an encryption is specified by number then one
 133 has to make sure that the Linux kernel knows about the encryption with that
 134 number, probably by patching the kernel. Standard numbers that are
 135 always present are 0 (no encryption) and 1 (XOR encryption).
 136 When the cryptoloop module is loaded (or compiled in), it uses number 18.
 137 This cryptoloop module will take the name of an arbitrary encryption type
 138 and find the module that knows how to perform that encryption.
 139
 140 .SH RETURN VALUE
 141 .B losetup
 142 returns 0 on success, nonzero on failure. When
 143 .B losetup
 144 displays the status of a loop device, it returns 1 if the device
 145 is not configured and 2 if an error occurred which prevented
 146 from determining the status of the device.
 147
 148 .SH FILES
 149 .TP
 150 .I /dev/loop[0..N]
 151 loop block devices
 152 .TP
 153 .I /dev/loop-cotrol
 154 loop control device
 155
 156 .SH EXAMPLE
 157 The following commands can be used as an example of using the loop device.
 158 .nf
 159 .IP
 160 # dd if=/dev/zero of=~/file.img bs=1MiB count=10
 161 # losetup --find --show ~/file.img
 162 /dev/loop0
 163 # mkfs -t ext2 /dev/loop0
 164 # mount /dev/loop0 /mnt
 165  ...
 166 # umount /dev/loop0
 167 # losetup --detach /dev/loop0
 168 .fi
 169 .SH AUTHORS
 170 Karel Zak <kzak@redhat.com>, based on original version from
 171 Theodore Ts'o <tytso@athena.mit.edu>
 172 .SH AVAILABILITY
 173 The losetup command is part of the util-linux package and is available from
 174 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.