[PATCH man-pages] open.2: improve O_PATH documentation.

[PATCH man-pages] open.2: improve O_PATH documentation.

[NeilBrown]

[-- Attachment #1: Type: text/plain, Size: 1714 bytes --]


- fstatfs is now permitted.
- ioctl isn't, and is worth listing explicitly
- O_PATH allows an automount point to be opened with
  triggering the mount.

All tested

Signed-off-by: NeilBrown <neilb@suse.com>
---
 man2/open.2 | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/man2/open.2 b/man2/open.2
index e3b00939790c..38d532397b02 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -585,6 +585,7 @@ The file itself is not opened, and other file operations (e.g.,
 .BR fchmod (2),
 .BR fchown (2),
 .BR fgetxattr (2),
+.BR ioctl (2),
 .BR mmap (2))
 fail with the error
 .BR EBADF .
@@ -599,8 +600,11 @@ be performed on the resulting file descriptor:
 (since Linux 3.5);
 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
 .BR fstat (2)
-(since Linux 3.6).
+(since Linux 3.6);
 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
+.BR fstatfs (2)
+(since Linux 3.12).
+.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
 .IP *
 Duplicating the file descriptor
 .RB ( dup (2),
@@ -666,6 +670,16 @@ argument in calls to
 and
 .BR readlinkat (2)
 with an empty pathname to have the calls operate on the symbolic link.
+
+If
+.I pathname
+refers to an automount point that has not yet been triggered, so no
+other filesystem is mounted on it, then the call returns a file
+descriptor referring to the automount directory without triggering a mount.
+.BR fstatfs (2)
+can then be used to determine if it is, in fact, an untriggered
+automount point
+.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
 .TP
 .B O_SYNC
 Write operations on the file will complete according to the requirements of
-- 
2.14.0.rc0.dirty


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[Lennart Poettering]

On Do, 10.08.17 13:25, NeilBrown (neilb@suse.com) wrote:

> +If
> +.I pathname
> +refers to an automount point that has not yet been triggered, so no
> +other filesystem is mounted on it, then the call returns a file
> +descriptor referring to the automount directory without triggering a mount.
> +.BR fstatfs (2)
> +can then be used to determine if it is, in fact, an untriggered
> +automount point
> +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).

Because Linux is broken you shouldn't compare f_type just like this,
and the man page probably shouldn't suggest that either I figure. The
only safe way is something like this:

     s.f_type == (typeof(s.f_type)) AUTOFS_SUPER_MAGIC

That's because f_type is defined with different types (both signed and
unsigned) on different archs, and the magic values tend to use the
full unsigned 32bit range...

(Yes, strictly speaking AUTOFS_SUPER_MAGIC isn't one of the unsigned
32bit ones, but I think it's better to stick the same rules for all
magic values comparisons here...)

(And yes, the statfs() man page only mentions the problem briefly,
without the typeof way out, but it really should)

Lennart

-- 
Lennart Poettering, Red Hat

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[Krzysztof Błaszkowski]

Mr Poettering,


I don't know exactly what is the whole discussion about but Mr
consider (very seriously) this regarding C language, C coding,
compilers and program execution:

claim #1: "==" is compare operator another words result is considered
to be true if both arguments are same binary

claim #2: it is possible to compare different types to each other, e.g.
int to char, long long to short

claim #3: if both arguments are of different sizes then compiler
extends shorter type to the size of larger argument padding with 0s.

claim #4: compiler uses type of variable for immediate constant when
comparing the variable to it. thus even bitfields comparisons work.

claim #5: the compiler is modern gcc

thus your whole thesis is damn crap especially your claim like "Linux
is broken". you could write glibc is broken because it does not
"expose" (which is not strictly true) the fsword_t 

Do you know what the term "Linux" stands for ?
I can give you explanation but there are so many other noble developers
which can do this better and it is disappointing that they haven't done
this yet.


I could ignore your email like others did but once upon I gave you a
proof that because systemd-logging can't do better recovery than
underlying file system then doing so by systemd-logging is utterly
stupid, so if you, Mr Poettering, stop doing more userspace crap then
whole "Linux" will only benefit from this.


And the Red Hat should fire you out.
I reckon that fools are the worst plague in the World and that's why I
stopped tolerating fools.
I am a racist - I hate fools.


On Thu, 2017-08-10 at 12:21 +0200, Lennart Poettering wrote:
> On Do, 10.08.17 13:25, NeilBrown (neilb@suse.com) wrote:
> 
> > 
> > +If
> > +.I pathname
> > +refers to an automount point that has not yet been triggered, so
> > no
> > +other filesystem is mounted on it, then the call returns a file
> > +descriptor referring to the automount directory without triggering
> > a mount.
> > +.BR fstatfs (2)
> > +can then be used to determine if it is, in fact, an untriggered
> > +automount point
> > +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
> 
> Because Linux is broken you shouldn't compare f_type just like this,
> and the man page probably shouldn't suggest that either I figure. The
> only safe way is something like this:
> 
>      s.f_type == (typeof(s.f_type)) AUTOFS_SUPER_MAGIC
> 
> That's because f_type is defined with different types (both signed
> and
> unsigned) on different archs, and the magic values tend to use the
> full unsigned 32bit range...
> 
> (Yes, strictly speaking AUTOFS_SUPER_MAGIC isn't one of the unsigned
> 32bit ones, but I think it's better to stick the same rules for all
> magic values comparisons here...)
> 
> (And yes, the statfs() man page only mentions the problem briefly,
> without the typeof way out, but it really should)
> 
> Lennart
> 
-- 
Krzysztof Blaszkowski

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[Matthew Wilcox]

On Thu, Aug 10, 2017 at 12:21:04PM +0200, Lennart Poettering wrote:
> On Do, 10.08.17 13:25, NeilBrown (neilb@suse.com) wrote:
> > +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
> 
> Because Linux is broken you shouldn't compare f_type just like this,
> and the man page probably shouldn't suggest that either I figure. The
> only safe way is something like this:
> 
>      s.f_type == (typeof(s.f_type)) AUTOFS_SUPER_MAGIC
> 
> That's because f_type is defined with different types (both signed and
> unsigned) on different archs, and the magic values tend to use the
> full unsigned 32bit range...

Please give an example where Neil's formulation would fail.

$ git grep -w f_type arch/*/include |cut -d: -f 2- |sort -u
	int		f_type;
	long		f_type;
	s32		f_type;
	__u32	f_type;
	u32		f_type;
	unsigned int	f_type;

I quote the C standard here for your convenience:

Otherwise,  the  integer  promotions  are  performed  on  both  operands.

Then  the following rules are applied to the promoted operands:
If both operands have the same type, then no further conversion is needed.

Otherwise, if both operands have signed integer types or both have unsigned
integer  types,  the  operand  with  the  type  of  lesser  integer
conversion  rank  is converted to the type of the operand with greater rank.

Otherwise,  if  the  operand  that  has  unsigned  integer  type  has  rank
greater  or equal  to  the  rank  of  the  type  of  the  other  operand,
then  the  operand  with signed  integer  type  is  converted  to  the  type
of  the  operand  with  unsigned integer type.

Otherwise, if the type of the operand with signed integer type can represent
all of the values of the type of the operand with unsigned integer type, then
the  operand  with  unsigned  integer  type  is  converted  to  the  type  of
the operand with signed integer type.

Otherwise,   both   operands   are   converted   to   the   unsigned   integer
type corresponding to the type of the operand with signed integer type

> (Yes, strictly speaking AUTOFS_SUPER_MAGIC isn't one of the unsigned
> 32bit ones, but I think it's better to stick the same rules for all
> magic values comparisons here...)
> 
> (And yes, the statfs() man page only mentions the problem briefly,
> without the typeof way out, but it really should)
> 
> Lennart
> 
> -- 
> Lennart Poettering, Red Hat

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[NeilBrown]

[-- Attachment #1: Type: text/plain, Size: 1836 bytes --]

On Thu, Aug 10 2017, Krzysztof Błaszkowski wrote:

> Mr Poettering,
>
>
> I don't know exactly what is the whole discussion about but Mr
> consider (very seriously) this regarding C language, C coding,
> compilers and program execution:
>
> claim #1: "==" is compare operator another words result is considered
> to be true if both arguments are same binary
>
> claim #2: it is possible to compare different types to each other, e.g.
> int to char, long long to short
>
> claim #3: if both arguments are of different sizes then compiler
> extends shorter type to the size of larger argument padding with 0s.
>
> claim #4: compiler uses type of variable for immediate constant when
> comparing the variable to it. thus even bitfields comparisons work.
>
> claim #5: the compiler is modern gcc
>
> thus your whole thesis is damn crap especially your claim like "Linux
> is broken". you could write glibc is broken because it does not
> "expose" (which is not strictly true) the fsword_t 
>
> Do you know what the term "Linux" stands for ?
> I can give you explanation but there are so many other noble developers
> which can do this better and it is disappointing that they haven't done
> this yet.
>
>
> I could ignore your email like others did but once upon I gave you a
> proof that because systemd-logging can't do better recovery than
> underlying file system then doing so by systemd-logging is utterly
> stupid, so if you, Mr Poettering, stop doing more userspace crap then
> whole "Linux" will only benefit from this.
>
>
> And the Red Hat should fire you out.
> I reckon that fools are the worst plague in the World and that's why I
> stopped tolerating fools.
> I am a racist - I hate fools.

Please keep the discussion civil.  This sort of language is not welcome.

NeilBrown

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[Michael Kerrisk (man-pages)]

On 08/10/2017 05:25 AM, NeilBrown wrote:
> 
> - fstatfs is now permitted.
> - ioctl isn't, and is worth listing explicitly
> - O_PATH allows an automount point to be opened with
>   triggering the mount.
> 
> All tested

Thanks, Neil. Patch applied.

Cheers,

Michael


> Signed-off-by: NeilBrown <neilb@suse.com>
> ---
>  man2/open.2 | 16 +++++++++++++++-
>  1 file changed, 15 insertions(+), 1 deletion(-)
> 
> diff --git a/man2/open.2 b/man2/open.2
> index e3b00939790c..38d532397b02 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -585,6 +585,7 @@ The file itself is not opened, and other file operations (e.g.,
>  .BR fchmod (2),
>  .BR fchown (2),
>  .BR fgetxattr (2),
> +.BR ioctl (2),
>  .BR mmap (2))
>  fail with the error
>  .BR EBADF .
> @@ -599,8 +600,11 @@ be performed on the resulting file descriptor:
>  (since Linux 3.5);
>  .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
>  .BR fstat (2)
> -(since Linux 3.6).
> +(since Linux 3.6);
>  .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
> +.BR fstatfs (2)
> +(since Linux 3.12).
> +.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
>  .IP *
>  Duplicating the file descriptor
>  .RB ( dup (2),
> @@ -666,6 +670,16 @@ argument in calls to
>  and
>  .BR readlinkat (2)
>  with an empty pathname to have the calls operate on the symbolic link.
> +
> +If
> +.I pathname
> +refers to an automount point that has not yet been triggered, so no
> +other filesystem is mounted on it, then the call returns a file
> +descriptor referring to the automount directory without triggering a mount.
> +.BR fstatfs (2)
> +can then be used to determine if it is, in fact, an untriggered
> +automount point
> +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
>  .TP
>  .B O_SYNC
>  Write operations on the file will complete according to the requirements of
> 


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

Re: [PATCH man-pages] open.2: improve O_PATH documentation.

[Michael Kerrisk (man-pages)]

On 08/11/2017 01:04 AM, NeilBrown wrote:
> On Thu, Aug 10 2017, Krzysztof Błaszkowski wrote:
> 
>> Mr Poettering,
>>
>>
>> I don't know exactly what is the whole discussion about but Mr
>> consider (very seriously) this regarding C language, C coding,
>> compilers and program execution:
>>
>> claim #1: "==" is compare operator another words result is considered
>> to be true if both arguments are same binary
>>
>> claim #2: it is possible to compare different types to each other, e.g.
>> int to char, long long to short
>>
>> claim #3: if both arguments are of different sizes then compiler
>> extends shorter type to the size of larger argument padding with 0s.
>>
>> claim #4: compiler uses type of variable for immediate constant when
>> comparing the variable to it. thus even bitfields comparisons work.
>>
>> claim #5: the compiler is modern gcc
>>
>> thus your whole thesis is damn crap especially your claim like "Linux
>> is broken". you could write glibc is broken because it does not
>> "expose" (which is not strictly true) the fsword_t 
>>
>> Do you know what the term "Linux" stands for ?
>> I can give you explanation but there are so many other noble developers
>> which can do this better and it is disappointing that they haven't done
>> this yet.
>>
>>
>> I could ignore your email like others did but once upon I gave you a
>> proof that because systemd-logging can't do better recovery than
>> underlying file system then doing so by systemd-logging is utterly
>> stupid, so if you, Mr Poettering, stop doing more userspace crap then
>> whole "Linux" will only benefit from this.
>>
>>
>> And the Red Hat should fire you out.
>> I reckon that fools are the worst plague in the World and that's why I
>> stopped tolerating fools.
>> I am a racist - I hate fools.
> 
> Please keep the discussion civil.  This sort of language is not welcome.

Thanks, Neil. Agreed.

Cheers,

Michael



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