summaryrefslogtreecommitdiffstats
path: root/man/man4/loop.4
blob: 19c1127056e2228964a741af2005be9854a3f27c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de)
.\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.TH loop 4 2024-05-02 "Linux man-pages (unreleased)"
.SH NAME
loop, loop-control \- loop devices
.SH SYNOPSIS
.nf
#include <linux/loop.h>
.fi
.SH DESCRIPTION
The loop device is a block device that maps its data blocks not to a
physical device such as a hard disk or optical disk drive,
but to the blocks of
a regular file in a filesystem or to another block device.
This can be useful for example to provide a block device for a filesystem
image stored in a file, so that it can be mounted with the
.BR mount (8)
command.
You could do
.P
.in +4n
.EX
$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
$ \fBsudo losetup /dev/loop4 file.img\fP
$ \fBsudo mkfs \-t ext4 /dev/loop4\fP
$ \fBsudo mkdir /myloopdev\fP
$ \fBsudo mount /dev/loop4 /myloopdev\fP
.EE
.in
.P
See
.BR losetup (8)
for another example.
.P
A transfer function can be specified for each loop device for
encryption and decryption purposes.
.P
The following
.BR ioctl (2)
operations are provided by the loop block device:
.TP
.B LOOP_SET_FD
Associate the loop device with the open file whose file descriptor is
passed as the (third)
.BR ioctl (2)
argument.
.TP
.B LOOP_CLR_FD
Disassociate the loop device from any file descriptor.
.TP
.B LOOP_SET_STATUS
Set the status of the loop device using the (third)
.BR ioctl (2)
argument.
This argument is a pointer to a
.I loop_info
structure, defined in
.I <linux/loop.h>
as:
.IP
.in +4n
.EX
struct loop_info {
    int           lo_number;      /* ioctl r/o */
    dev_t         lo_device;      /* ioctl r/o */
    unsigned long lo_inode;       /* ioctl r/o */
    dev_t         lo_rdevice;     /* ioctl r/o */
    int           lo_offset;
    int           lo_encrypt_type;
    int           lo_encrypt_key_size;  /* ioctl w/o */
    int           lo_flags;       /* ioctl r/w (r/o before
                                     Linux 2.6.25) */
    char          lo_name[LO_NAME_SIZE];
    unsigned char lo_encrypt_key[LO_KEY_SIZE];
                                  /* ioctl w/o */
    unsigned long lo_init[2];
    char          reserved[4];
};
.EE
.in
.IP
The encryption type
.RI ( lo_encrypt_type )
should be one of
.BR LO_CRYPT_NONE ,
.BR LO_CRYPT_XOR ,
.BR LO_CRYPT_DES ,
.BR LO_CRYPT_FISH2 ,
.BR LO_CRYPT_BLOW ,
.BR LO_CRYPT_CAST128 ,
.BR LO_CRYPT_IDEA ,
.BR LO_CRYPT_DUMMY ,
.BR LO_CRYPT_SKIPJACK ,
or (since Linux 2.6.0)
.BR LO_CRYPT_CRYPTOAPI .
.IP
The
.I lo_flags
field is a bit mask that can include zero or more of the following:
.RS
.TP
.B LO_FLAGS_READ_ONLY
The loopback device is read-only.
.TP
.BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)"
.\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581
The loopback device will autodestruct on last close.
.TP
.BR LO_FLAGS_PARTSCAN " (since Linux 3.2)"
.\" commit e03c8dd14915fabc101aa495828d58598dc5af98
Allow automatic partition scanning.
.TP
.BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)"
.\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3
Use direct I/O mode to access the backing file.
.RE
.IP
The only
.I lo_flags
that can be modified by
.B LOOP_SET_STATUS
are
.B LO_FLAGS_AUTOCLEAR
and
.BR LO_FLAGS_PARTSCAN .
.TP
.B LOOP_GET_STATUS
Get the status of the loop device.
The (third)
.BR ioctl (2)
argument must be a pointer to a
.IR "struct loop_info" .
.TP
.BR LOOP_CHANGE_FD " (since Linux 2.6.5)"
Switch the backing store of the loop device to the new file identified
file descriptor specified in the (third)
.BR ioctl (2)
argument, which is an integer.
This operation is possible only if the loop device is read-only and
the new backing store is the same size and type as the old backing store.
.TP
.BR LOOP_SET_CAPACITY " (since Linux 2.6.30)"
.\" commit 53d6660836f233df66490707365ab177e5fb2bb4
Resize a live loop device.
One can change the size of the underlying backing store and then use this
operation so that the loop driver learns about the new size.
This operation takes no argument.
.TP
.BR LOOP_SET_DIRECT_IO " (since Linux 4.10)"
.\" commit ab1cb278bc7027663adbfb0b81404f8398437e11
Set DIRECT I/O mode on the loop device, so that
it can be used to open backing file.
The (third)
.BR ioctl (2)
argument is an unsigned long value.
A nonzero represents direct I/O mode.
.TP
.BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)"
.\" commit 89e4fdecb51cf5535867026274bc97de9480ade5
Set the block size of the loop device.
The (third)
.BR ioctl (2)
argument is an unsigned long value.
This value must be a power of two in the range
[512,pagesize];
otherwise, an
.B EINVAL
error results.
.TP
.BR LOOP_CONFIGURE " (since Linux 5.8)"
.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae
Setup and configure all loop device parameters in a single step using
the (third)
.BR ioctl (2)
argument.
This argument is a pointer to a
.I loop_config
structure, defined in
.I <linux/loop.h>
as:
.IP
.in +4n
.EX
struct loop_config {
    __u32               fd;
    __u32               block_size;
    struct loop_info64  info;
    __u64               __reserved[8];
};
.EE
.in
.IP
In addition to doing what
.B LOOP_SET_STATUS
can do,
.B LOOP_CONFIGURE
can also be used to do the following:
.RS
.IP \[bu] 3
set the correct block size immediately by setting
.IR loop_config.block_size ;
.IP \[bu]
explicitly request direct I/O mode by setting
.B LO_FLAGS_DIRECT_IO
in
.IR loop_config.info.lo_flags ;
and
.IP \[bu]
explicitly request read-only mode by setting
.B LO_FLAGS_READ_ONLY
in
.IR loop_config.info.lo_flags .
.RE
.P
Since Linux 2.6, there are two new
.BR ioctl (2)
operations:
.TP
.B LOOP_SET_STATUS64
.TQ
.B LOOP_GET_STATUS64
These are similar to
.BR LOOP_SET_STATUS " and " LOOP_GET_STATUS
described above but use the
.I loop_info64
structure,
which has some additional fields and a larger range for some other fields:
.IP
.in +4n
.EX
struct loop_info64 {
    uint64_t lo_device;           /* ioctl r/o */
    uint64_t lo_inode;            /* ioctl r/o */
    uint64_t lo_rdevice;          /* ioctl r/o */
    uint64_t lo_offset;
    uint64_t lo_sizelimit;  /* bytes, 0 == max available */
    uint32_t lo_number;           /* ioctl r/o */
    uint32_t lo_encrypt_type;
    uint32_t lo_encrypt_key_size; /* ioctl w/o */
    uint32_t lo_flags; i          /* ioctl r/w (r/o before
                                     Linux 2.6.25) */
    uint8_t  lo_file_name[LO_NAME_SIZE];
    uint8_t  lo_crypt_name[LO_NAME_SIZE];
    uint8_t  lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */
    uint64_t lo_init[2];
};
.EE
.in
.SS /dev/loop-control
Since Linux 3.1,
.\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844
the kernel provides the
.I /dev/loop\-control
device, which permits an application to dynamically find a free device,
and to add and remove loop devices from the system.
To perform these operations, one first opens
.I /dev/loop\-control
and then employs one of the following
.BR ioctl (2)
operations:
.TP
.B LOOP_CTL_GET_FREE
Allocate or find a free loop device for use.
On success, the device number is returned as the result of the call.
This operation takes no argument.
.TP
.B LOOP_CTL_ADD
Add the new loop device whose device number is specified
as a long integer in the third
.BR ioctl (2)
argument.
On success, the device index is returned as the result of the call.
If the device is already allocated, the call fails with the error
.BR EEXIST .
.TP
.B LOOP_CTL_REMOVE
Remove the loop device whose device number is specified
as a long integer in the third
.BR ioctl (2)
argument.
On success, the device number is returned as the result of the call.
If the device is in use, the call fails with the error
.BR EBUSY .
.SH FILES
.TP
.I /dev/loop*
The loop block special device files.
.SH EXAMPLES
The program below uses the
.I /dev/loop\-control
device to find a free loop device, opens the loop device,
opens a file to be used as the underlying storage for the device,
and then associates the loop device with the backing store.
The following shell session demonstrates the use of the program:
.P
.in +4n
.EX
$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
10+0 records in
10+0 records out
10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
$ \fBsudo ./mnt_loop file.img\fP
loopname = /dev/loop5
.EE
.in
.SS Program source
\&
.EX
#include <fcntl.h>
#include <linux/loop.h>
#include <sys/ioctl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
\&
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
                        } while (0)
\&
int
main(int argc, char *argv[])
{
    int loopctlfd, loopfd, backingfile;
    long devnr;
    char loopname[4096];
\&
    if (argc != 2) {
        fprintf(stderr, "Usage: %s backing\-file\en", argv[0]);
        exit(EXIT_FAILURE);
    }
\&
    loopctlfd = open("/dev/loop\-control", O_RDWR);
    if (loopctlfd == \-1)
        errExit("open: /dev/loop\-control");
\&
    devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE);
    if (devnr == \-1)
        errExit("ioctl\-LOOP_CTL_GET_FREE");
\&
    sprintf(loopname, "/dev/loop%ld", devnr);
    printf("loopname = %s\en", loopname);
\&
    loopfd = open(loopname, O_RDWR);
    if (loopfd == \-1)
        errExit("open: loopname");
\&
    backingfile = open(argv[1], O_RDWR);
    if (backingfile == \-1)
        errExit("open: backing\-file");
\&
    if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1)
        errExit("ioctl\-LOOP_SET_FD");
\&
    exit(EXIT_SUCCESS);
}
.EE
.SH SEE ALSO
.BR losetup (8),
.BR mount (8)