Skip to contentSkip to conversation

loop.4: add some details about lo_flags

PATCH Superseded Michael Kerrisk (man-pages) 2 participants 5 messages Sep 9, 2020 – Sep 10, 2020 1 message not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): 5102fd63-a2e0-7bad-e8ef-e310acd65394@gmail

Yang Xu

#1 lore raw

PATCH v3 1/2 loop.4: add some details about lo_flags

Signed-off-by Yang Xu <[email protected]>
---
 man4/loop.4 | 8 ++++++++
 1 file changed, 8 insertions(+)
man4/loop.4 +8 -0
index f4cf48043..5cc9a7e79 100644
@@ -136,6 +136,14 @@ Allow automatic partition scanning.
 Use direct I/O mode to access the backing file.
 .RE
 .TP
+The
+.BR LOOP_SET_STATUS
+can neither set the
+.BR LO_FLAGS_READ_ONLY
+nor
+.BR LO_FLAGS_DIRECT_IO
+lo_flags because they are exclusively set from kernel.
+.TP
 .B LOOP_GET_STATUS
 Get the status of the loop device.
 The (third)
Signature · 1 line
2.23.0
author
#2 lore raw

Hello Yang Xu,

Quoted 14 lines · Yang Xu
Signed-off-by Yang Xu <[email protected]>
---
 man4/loop.4 | 8 ++++++++
 1 file changed, 8 insertions(+)
man4/loop.4 +1 -0
index f4cf48043..5cc9a7e79 100644
@@ -136,6 +136,14 @@ Allow automatic partition scanning.
 Use direct I/O mode to access the backing file.
 .RE
 .TP
+The

man4/loop.4 Allow automatic partition scanning. · line 149

Quoted 10 lines
man4/loop.4 +7 -0
+.BR LOOP_SET_STATUS
+can neither set the
+.BR LO_FLAGS_READ_ONLY
+nor
+.BR LO_FLAGS_DIRECT_IO
+lo_flags because they are exclusively set from kernel.
+.TP
 .B LOOP_GET_STATUS
 Get the status of the loop device.
 The (third)

Looking at the kernel code:

[[

Quoted 1 line

/* LO_FLAGS that can be set using LOOP_SET_STATUS(64) */

#define LOOP_SET_STATUS_SETTABLE_FLAGS (LO_FLAGS_AUTOCLEAR | LO_FLAGS_PARTSCAN)

/* LO_FLAGS that can be cleared using LOOP_SET_STATUS(64) */ #define LOOP_SET_STATUS_CLEARABLE_FLAGS (LO_FLAGS_AUTOCLEAR)

/* LO_FLAGS that can be set using LOOP_CONFIGURE */
#define LOOP_CONFIGURE_SETTABLE_FLAGS (LO_FLAGS_READ_ONLY | LO_FLAGS_AUTOCLEAR \
| LO_FLAGS_PARTSCAN | LO_FLAGS_DIRECT_IO)
]]

and

[[

        /* Mask out flags that can't be set using LOOP_SET_STATUS. */
        lo->lo_flags &= LOOP_SET_STATUS_SETTABLE_FLAGS;
        /* For those flags, use the previous values instead */
        lo->lo_flags |= prev_lo_flags & ~LOOP_SET_STATUS_SETTABLE_FLAGS;
        /* For flags that can't be cleared, use previous values too */
        lo->lo_flags |= prev_lo_flags & ~LOOP_SET_STATUS_CLEARABLE_FLAGS;

]]

would it not be clearer and simpler just to say something like:

[[
The only lo_flags that can be modified using LOOP_SET_STATUS are LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.
]]

?

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#3 lore raw

Hi Michael

Quoted 51 lines

Hello Yang Xu,

Quoted 14 lines · Yang Xu
Signed-off-by Yang Xu <[email protected]>
---
  man4/loop.4 | 8 ++++++++
  1 file changed, 8 insertions(+)
man4/loop.4 +1 -0
index f4cf48043..5cc9a7e79 100644
@@ -136,6 +136,14 @@ Allow automatic partition scanning.
  Use direct I/O mode to access the backing file.
  .RE
  .TP
+The

man4/loop.4 Allow automatic partition scanning. · line 149

Quoted 10 lines
man4/loop.4 +7 -0
+.BR LOOP_SET_STATUS
+can neither set the
+.BR LO_FLAGS_READ_ONLY
+nor
+.BR LO_FLAGS_DIRECT_IO
+lo_flags because they are exclusively set from kernel.
+.TP
  .B LOOP_GET_STATUS
  Get the status of the loop device.
  The (third)

Looking at the kernel code:

[[

Quoted 1 line

/* LO_FLAGS that can be set using LOOP_SET_STATUS(64) */

#define LOOP_SET_STATUS_SETTABLE_FLAGS (LO_FLAGS_AUTOCLEAR | LO_FLAGS_PARTSCAN)

/* LO_FLAGS that can be cleared using LOOP_SET_STATUS(64) */ #define LOOP_SET_STATUS_CLEARABLE_FLAGS (LO_FLAGS_AUTOCLEAR)

/* LO_FLAGS that can be set using LOOP_CONFIGURE */
#define LOOP_CONFIGURE_SETTABLE_FLAGS (LO_FLAGS_READ_ONLY | LO_FLAGS_AUTOCLEAR \
| LO_FLAGS_PARTSCAN | LO_FLAGS_DIRECT_IO)
]]

and

[[

         /* Mask out flags that can't be set using LOOP_SET_STATUS. */
         lo->lo_flags &= LOOP_SET_STATUS_SETTABLE_FLAGS;
         /* For those flags, use the previous values instead */
         lo->lo_flags |= prev_lo_flags & ~LOOP_SET_STATUS_SETTABLE_FLAGS;
         /* For flags that can't be cleared, use previous values too */
         lo->lo_flags |= prev_lo_flags & ~LOOP_SET_STATUS_CLEARABLE_FLAGS;
Quoted 7 lines

]]

would it not be clearer and simpler just to say something like:

[[
The only lo_flags that can be modified using LOOP_SET_STATUS are LO_FLAGS_AUTOCLEAR and LO_FLAGS_PARTSCAN.

Thanks. Will use more clear sentence on v4.

Best Regards
Yang Xu

Quoted 8 lines

]]

?

Thanks,

Michael

#4 lore raw

PATCH v3 2/2 loop.4: Document LOOP_CONFIGURE ioctl

In reply to Yang Xu
Signed-off-by Yang Xu <[email protected]>
---
 man4/loop.4 | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
man4/loop.4 +43 -0
index 5cc9a7e79..c935be749 100644
@@ -186,6 +186,49 @@ This value must be a power of two in the range
 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
+.BR LOOP_SET_STATUS
+can do,
+.BR LOOP_CONFIGURE
+can also be used to the following:
+.RS
+.IP * 2
+Set the correct block size immediately by setting
+.IR loop_config.block_size.
+.IP *
+Explicitly request direct I/O mode by setting
+.BR LO_FLAGS_DIRECT_IO
+in loop_config.info.lo_flags.
+.IP *
+Explicitly request read-only mode by setting
+.BR LO_FLAGS_READ_ONLY
+in
+.IR loop_config.info.lo_flags.
+.RE
 .PP
 Since Linux 2.6, there are two new
 .BR ioctl (2)
Signature · 1 line
2.23.0
author
#5 lore raw

Re: [PATCH v3 2/2] loop.4: Document LOOP_CONFIGURE ioctl

Quoted 2 lines · Yang Xu
Signed-off-by Yang Xu <[email protected]>

---

Thanks, Yang Xu. Patch applied.

Cheers,

Michael

Quoted 58 lines
 man4/loop.4 | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
man4/loop.4 +43 -0
index 5cc9a7e79..c935be749 100644
@@ -186,6 +186,49 @@ This value must be a power of two in the range
 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
+.BR LOOP_SET_STATUS
+can do,
+.BR LOOP_CONFIGURE
+can also be used to the following:
+.RS
+.IP * 2
+Set the correct block size immediately by setting
+.IR loop_config.block_size.
+.IP *
+Explicitly request direct I/O mode by setting
+.BR LO_FLAGS_DIRECT_IO
+in loop_config.info.lo_flags.
+.IP *
+Explicitly request read-only mode by setting
+.BR LO_FLAGS_READ_ONLY
+in
+.IR loop_config.info.lo_flags.
+.RE
 .PP
 Since Linux 2.6, there are two new
 .BR ioctl (2)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/