diff options
Diffstat (limited to 'man/man4/loop.4')
| -rw-r--r-- | man/man4/loop.4 | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/man/man4/loop.4 b/man/man4/loop.4 new file mode 100644 index 0000000..19c1127 --- /dev/null +++ b/man/man4/loop.4 @@ -0,0 +1,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) |