Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)