[PATCH] loop.4: Document loop_configure ioctl

[PATCH] loop.4: Document loop_configure ioctl

[Yang Xu]

Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
---
 man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/man4/loop.4 b/man4/loop.4
index 2dcbac807..abf722a25 100644
--- a/man4/loop.4
+++ b/man4/loop.4
@@ -177,6 +177,41 @@ 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 using the (third)
+.BR ioctl (2)
+argument at once.
+This argument is a pointer to
+.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 set the correct block size immediately
+by setting loop_config.block_size. Explicitly request
+direct I/O mode by setting
+.BR LO_FLAGS_DIRECT_IO
+in loop_config.info.lo_flags. Explicitly request read-only
+mode by setting
+.BR LO_FLAGS_READ_ONLY
+in loop_config.info.lo_flags.
 .PP
 Since Linux 2.6, there are two new
 .BR ioctl (2)
-- 
2.23.0

Re: [PATCH] loop.4: Document loop_configure ioctl

[Michael Kerrisk (man-pages)]

Hello Yang Xu,

Thank you for your patch. Please see my comments below.

On Mon, 3 Aug 2020 at 04:38, Yang Xu <xuyang2018.jy@cn.fujitsu.com> wrote:
>
> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
> ---
>  man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
>
> diff --git a/man4/loop.4 b/man4/loop.4
> index 2dcbac807..abf722a25 100644
> --- a/man4/loop.4
> +++ b/man4/loop.4
> @@ -177,6 +177,41 @@ 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 using the (third)
> +.BR ioctl (2)
> +argument at once.
> +This argument is a pointer to
> +.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 set the correct block size immediately
> +by setting loop_config.block_size. Explicitly request
> +direct I/O mode by setting
> +.BR LO_FLAGS_DIRECT_IO
> +in loop_config.info.lo_flags. Explicitly request read-only
> +mode by setting
> +.BR LO_FLAGS_READ_ONLY
> +in loop_config.info.lo_flags.

The last two sentences (starting "Explicitly request") are hard for me
to understand. Could you expand the wording here a little please to
clarify?

Thanks,

Michael

>  .PP
>  Since Linux 2.6, there are two new
>  .BR ioctl (2)
> --
> 2.23.0
>
>
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] loop.4: Document loop_configure ioctl

[Yang Xu]

Hi Michael

> Hello Yang Xu,
> 
> Thank you for your patch. Please see my comments below.
> 
> On Mon, 3 Aug 2020 at 04:38, Yang Xu <xuyang2018.jy@cn.fujitsu.com> wrote:
>>
>> Signed-off-by: Yang Xu <xuyang2018.jy@cn.fujitsu.com>
>> ---
>>   man4/loop.4 | 35 +++++++++++++++++++++++++++++++++++
>>   1 file changed, 35 insertions(+)
>>
>> diff --git a/man4/loop.4 b/man4/loop.4
>> index 2dcbac807..abf722a25 100644
>> --- a/man4/loop.4
>> +++ b/man4/loop.4
>> @@ -177,6 +177,41 @@ 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 using the (third)
>> +.BR ioctl (2)
>> +argument at once.
>> +This argument is a pointer to
>> +.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 set the correct block size immediately
>> +by setting loop_config.block_size. Explicitly request
>> +direct I/O mode by setting
>> +.BR LO_FLAGS_DIRECT_IO
>> +in loop_config.info.lo_flags. Explicitly request read-only
>> +mode by setting
>> +.BR LO_FLAGS_READ_ONLY
>> +in loop_config.info.lo_flags.
> 
> The last two sentences (starting "Explicitly request") are hard for me
> to understand. Could you expand the wording here a little please to
> clarify?

In drivers/block/loop.c code, set status function(loop_set_status) 
doesn't handle LO_FLAGS_READ_ONLY flag and ingore it. it is the same for
LO_FLAGS_DIRECT_IO flag. "Explicitly request" is compared with 
LOOP_SET_STATUS ioctl.

Best Regards
Yang Xu
> 
> Thanks,
> 
> Michael
> 
>>   .PP
>>   Since Linux 2.6, there are two new
>>   .BR ioctl (2)
>> --
>> 2.23.0
>>
>>
>>
> 
>