|
HTML rendering created 2023-12-22 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
|
loop(4) Kernel Interfaces Manual loop(4)
loop, loop-control - loop devices
#include <linux/loop.h>
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 mount(8) command. You could do
$ dd if=/dev/zero of=file.img bs=1MiB count=10
$ sudo losetup /dev/loop4 file.img
$ sudo mkfs -t ext4 /dev/loop4
$ sudo mkdir /myloopdev
$ sudo mount /dev/loop4 /myloopdev
See losetup(8) for another example.
A transfer function can be specified for each loop device for
encryption and decryption purposes.
The following ioctl(2) operations are provided by the loop block
device:
LOOP_SET_FD
Associate the loop device with the open file whose file
descriptor is passed as the (third) ioctl(2) argument.
LOOP_CLR_FD
Disassociate the loop device from any file descriptor.
LOOP_SET_STATUS
Set the status of the loop device using the (third)
ioctl(2) argument. This argument is a pointer to a
loop_info structure, defined in <linux/loop.h> as:
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];
};
The encryption type (lo_encrypt_type) should be one of
LO_CRYPT_NONE, LO_CRYPT_XOR, LO_CRYPT_DES, LO_CRYPT_FISH2,
LO_CRYPT_BLOW, LO_CRYPT_CAST128, LO_CRYPT_IDEA,
LO_CRYPT_DUMMY, LO_CRYPT_SKIPJACK, or (since Linux 2.6.0)
LO_CRYPT_CRYPTOAPI.
The lo_flags field is a bit mask that can include zero or
more of the following:
LO_FLAGS_READ_ONLY
The loopback device is read-only.
LO_FLAGS_AUTOCLEAR (since Linux 2.6.25)
The loopback device will autodestruct on last
close.
LO_FLAGS_PARTSCAN (since Linux 3.2)
Allow automatic partition scanning.
LO_FLAGS_DIRECT_IO (since Linux 4.10)
Use direct I/O mode to access the backing file.
The only lo_flags that can be modified by LOOP_SET_STATUS
are LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.
LOOP_GET_STATUS
Get the status of the loop device. The (third) ioctl(2)
argument must be a pointer to a struct loop_info.
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)
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.
LOOP_SET_CAPACITY (since Linux 2.6.30)
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.
LOOP_SET_DIRECT_IO (since Linux 4.10)
Set DIRECT I/O mode on the loop device, so that it can be
used to open backing file. The (third) ioctl(2) argument
is an unsigned long value. A nonzero represents direct
I/O mode.
LOOP_SET_BLOCK_SIZE (since Linux 4.14)
Set the block size of the loop device. The (third)
ioctl(2) argument is an unsigned long value. This value
must be a power of two in the range [512,pagesize];
otherwise, an EINVAL error results.
LOOP_CONFIGURE (since Linux 5.8)
Setup and configure all loop device parameters in a single
step using the (third) ioctl(2) argument. This argument
is a pointer to a loop_config structure, defined in
<linux/loop.h> as:
struct loop_config {
__u32 fd;
__u32 block_size;
struct loop_info64 info;
__u64 __reserved[8];
};
In addition to doing what LOOP_SET_STATUS can do,
LOOP_CONFIGURE can also be used to do the following:
• set the correct block size immediately by setting
loop_config.block_size;
• explicitly request direct I/O mode by setting
LO_FLAGS_DIRECT_IO in loop_config.info.lo_flags; and
• explicitly request read-only mode by setting
LO_FLAGS_READ_ONLY in loop_config.info.lo_flags.
Since Linux 2.6, there are two new ioctl(2) operations:
LOOP_SET_STATUS64, LOOP_GET_STATUS64
These are similar to LOOP_SET_STATUS and LOOP_GET_STATUS
described above but use the loop_info64 structure, which
has some additional fields and a larger range for some
other fields:
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];
};
/dev/loop-control
Since Linux 3.1, the kernel provides the /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 /dev/loop-control and
then employs one of the following ioctl(2) operations:
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.
LOOP_CTL_ADD
Add the new loop device whose device number is specified
as a long integer in the third 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 EEXIST.
LOOP_CTL_REMOVE
Remove the loop device whose device number is specified as
a long integer in the third 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 EBUSY.
/dev/loop*
The loop block special device files.
The program below uses the /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:
$ dd if=/dev/zero of=file.img bs=1MiB count=10
10+0 records in
10+0 records out
10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s
$ sudo ./mnt_loop file.img
loopname = /dev/loop5
Program source
#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); \
} 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\n", 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\n", 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);
}
losetup(8), mount(8)
Linux man-pages (unreleased) (date) loop(4)
|
HTML rendering created 2023-12-22 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|