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 [ \-r ]
  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 binary (2^N)
  73 suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
  74 same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
  75
  76 .IP "\fB\-a, \-\-all\fP"
  77 show status of all loop devices
  78 .IP "\fB\-c, \-\-set-capacity\fP \fIloopdev\fP
  79 force loop driver to reread size of the file associated with the specified loop device
  80 .IP "\fB\-d, \-\-detach\fP \fIloopdev\fP..."
  81 detach the file or device associated with the specified loop device(s)
  82 .IP "\fB\-e, \-E, \-\-encryption \fIencryption_type\fP"
  83 enable data encryption with specified name or number
  84 .IP "\fB\-f, \-\-find\fP"
  85 find the first unused loop device. If a
  86 .I file
  87 argument is present, use this device. Otherwise, print its name
  88 .IP "\fB\-h, \-\-help\fP"
  89 print help
  90 .IP "\fB\-j, \-\-associated \fIfile\fP"
  91 show status of all loop devices associated with given
  92 .I file
  93 .IP "\fB\-o, \-\-offset \fIoffset\fP"
  94 the data start is moved \fIoffset\fP bytes into the specified file or
  95 device
  96 .IP "\fB\-\-sizelimit \fIsize\fP"
  97 the data end is set to no more than \fIsize\fP bytes after the data start
  98 .IP "\fB\-p, \-\-pass-fd \fInum\fP"
  99 read the passphrase from file descriptor with number
 100 .I num
 101 instead of from the terminal
 102 .IP "\fB\-r, \-\-read-only\fP"
 103 setup read-only loop device
 104 .IP "\fB\-\-show\fP"
 105 print device name if the
 106 .I -f
 107 option and a
 108 .I file
 109 argument are present.
 110 .IP "\fB\-v, \-\-verbose\fP"
 111 verbose mode
 112
 113 .SH ENCRYPTION
 114 .B Cryptoloop is deprecated in favor of dm-crypt. For more details see
 115 .B cryptsetup (8). It is possible that all bug reports regarding to -E/-e
 116 .B options will be ignored.
 117
 118
 119 It is possible to specify transfer functions (for encryption/decryption
 120 or other purposes) using one of the
 121 .B \-E
 122 and
 123 .B \-e
 124 options.
 125 There are two mechanisms to specify the desired encryption: by number
 126 and by name. If an encryption is specified by number then one
 127 has to make sure that the Linux kernel knows about the encryption with that
 128 number, probably by patching the kernel. Standard numbers that are
 129 always present are 0 (no encryption) and 1 (XOR encryption).
 130 When the cryptoloop module is loaded (or compiled in), it uses number 18.
 131 This cryptoloop module will take the name of an arbitrary encryption type
 132 and find the module that knows how to perform that encryption.
 133
 134 .SH RETURN VALUE
 135 .B losetup
 136 returns 0 on success, nonzero on failure. When
 137 .B losetup
 138 displays the status of a loop device, it returns 1 if the device
 139 is not configured and 2 if an error occurred which prevented
 140 from determining the status of the device.
 141
 142 .SH FILES
 143 .TP
 144 .I /dev/loop[0..N]
 145 loop block devices
 146 .TP
 147 .I /dev/loop-cotrol
 148 loop control device
 149
 150 .SH EXAMPLE
 151 The following commands can be used as an example of using the loop device.
 152 .nf
 153 .IP
 154 # dd if=/dev/zero of=~/file.img bs=1MiB count=10
 155 # losetup --find --show ~/file.img
 156 /dev/loop0
 157 # mkfs -t ext2 /dev/loop0
 158 # mount /dev/loop0 /mnt
 159  ...
 160 # umount /dev/loop0
 161 # losetup --detach /dev/loop0
 162 .fi
 163 .SH AUTHORS
 164 Karel Zak <kzak@redhat.com>, based on original version from
 165 Theodore Ts'o <tytso@athena.mit.edu>
 166 .SH AVAILABILITY
 167 The losetup command is part of the util-linux package and is available from
 168 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.