Re: ioperm(2): confusing terminology

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Oops; I've fixed the mailing list address now.


Cheers,
Alex

> Date: 2026-09-13 00:24:17+0200
> From: Alejandro Colomar <alx@kernel.org>
>
> Hi astian,
> 
> > Date: 2026-09-12 22:00:57+0000
> > From: astian <astian@memeware.net>
> >
> > ioperm(2) says:
> > 
> >   int ioperm(unsigned long from, unsigned long num, int turn_on);
> > 
> >   ioperm() sets the port access permission bits for the calling thread
> >   for num bits starting from port address from.  If turn_on is nonzero,
> >   then permission for the specified bits is enabled; otherwise it is
> >   disabled. [...]
> > 
> > The use of "bits" here is confusing/sloppy.
> > 
> > ioperm is supposed to enable or disable permission to access IO ports
> > for the calling thread.  In this API, the "permission bit" (singular) is
> > really "turn_on": 0 to disable access, non-zero to enable.  However this
> > description refers also "num bits starting from port address from" and
> > "the specified bits".  That seems to suggest that IO ports somehow refer
> > to "bits" and this API controls access permission to them, which is
> > bewildering.
> > 
> > Searching around I have seen that other versions of this manpage used to
> > say "bytes" instead of "bits", which is only slightly less bewildering.
> > Ports/addresses in the IO space refer neither to bits nor to bytes per
> > se, they are an abstract interface, like a syscall number/index.
> > (Architecturally, in some cases, these indices may in fact map to
> > processor registers which may in fact be portions of a contiguous
> > internal memory, so in some cases one could correctly say that the ports
> > refer to "bytes" in such memory, but this is obviously all very
> > low-level and microarchitecture-specific.  I think being aware of such
> > details actually makes this description more confusing.)
> > 
> > Apparently the reason for this confusing description is that for Linux
> > ioperm is a syscall and the kernel implements this syscall using a
> > bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> > sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> > 
> > Thus "num bits starting from port address from" actually refers to the
> > bits of that bitmap: the bits [from, from+num) are set according to
> > turn_on.
> > 
> > This kind of implicit reference to implementation details is wicked.
> > 
> > Suggested change:
> > 
> >   ioperm() sets the calling thread's access permission for num ports
> >   starting from port address from.  If turn_on is nonzero, then
> >   permission for the specified ports is enabled; otherwise it is
> >   disabled. [...]
> 
> Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> I write it?  (I don't mind; just asking in case you want to do it.)
> 
> > PS: Oh, also, maybe the title should say "set input/output port
> > permissions" instead of "set port input/output permissions".
> 
> Same here.
> 
> BTW, the manual page also says:
> 
>      This  call  is  mostly for the i386 architecture.  On many
>      other architectures it does not exist or will  always  re‐
>      turn an error.
> 
> Is this still true?
> 
> Another issue:
> 
>      EIO    (on PowerPC) This call is not supported.
> 
> Is this really true?  Where this is not supported, I expect ENOSYS.
> 
> And yet another thing: should we document the parameters as being
> uintptr_t instead of unsigned long?  They are the same exact type
> always, AFAIK.  Or is there any system where they aren't?  If they are
> the same, uintptr_t will better document that they are addresses.
> 
> 
> Have a lovely night!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es>



-- 
<https://www.alejandro-colomar.es>

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

Re: ioperm(2): confusing terminology

[astian]

On 13 Sep 2026 00:24 +0200, Alejandro Colomar wrote:
> Hi astian,

Hi.

>> Date: 2026-09-12 22:00:57+0000
>> From: astian <astian@memeware.net>
>>
>> ioperm(2) says:
>>
>>   int ioperm(unsigned long from, unsigned long num, int turn_on);
>>
>>   ioperm() sets the port access permission bits for the calling thread
>>   for num bits starting from port address from.  If turn_on is nonzero,
>>   then permission for the specified bits is enabled; otherwise it is
>>   disabled. [...]
>>
>> The use of "bits" here is confusing/sloppy.
>>
>> ioperm is supposed to enable or disable permission to access IO ports
>> for the calling thread.  In this API, the "permission bit" (singular) is
>> really "turn_on": 0 to disable access, non-zero to enable.  However this
>> description refers also "num bits starting from port address from" and
>> "the specified bits".  That seems to suggest that IO ports somehow refer
>> to "bits" and this API controls access permission to them, which is
>> bewildering.
>>
>> Searching around I have seen that other versions of this manpage used to
>> say "bytes" instead of "bits", which is only slightly less bewildering.
>> Ports/addresses in the IO space refer neither to bits nor to bytes per
>> se, they are an abstract interface, like a syscall number/index.
>> (Architecturally, in some cases, these indices may in fact map to
>> processor registers which may in fact be portions of a contiguous
>> internal memory, so in some cases one could correctly say that the ports
>> refer to "bytes" in such memory, but this is obviously all very
>> low-level and microarchitecture-specific.  I think being aware of such
>> details actually makes this description more confusing.)
>>
>> Apparently the reason for this confusing description is that for Linux
>> ioperm is a syscall and the kernel implements this syscall using a
>> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
>> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
>>
>> Thus "num bits starting from port address from" actually refers to the
>> bits of that bitmap: the bits [from, from+num) are set according to
>> turn_on.
>>
>> This kind of implicit reference to implementation details is wicked.

To complete the picture: this is not a mere Linux-specific
implementation detail.  At least for x86 (IA-32) it is inherited from
the processor architecture: the port permission bitmap is linked from
the structure pointed to by the "Task State Segment" (TSS) and checked
by the processor.

It is still an implicit reference to an implementation detail.  I think
not mentioning this bits-and-bitmaps business is better but
alternatively the reference should be made explicit and the kernel
bitmap should be mentioned (and for x86 perhaps also the TSS).

>> Suggested change:
>>
>>   ioperm() sets the calling thread's access permission for num ports
>>   starting from port address from.  If turn_on is nonzero, then
>>   permission for the specified ports is enabled; otherwise it is
>>   disabled. [...]
>
> Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> I write it?  (I don't mind; just asking in case you want to do it.)
>
>> PS: Oh, also, maybe the title should say "set input/output port
>> permissions" instead of "set port input/output permissions".
>
> Same here.

Sorry, I've never written *roff before and I don't think I want to spend
my time learning that... although, I might be able do this by just
blindly replacing words without touching the escapes...

Which bring up the question, why not moving to a less hairy source
format?

> BTW, the manual page also says:
>
>      This  call  is  mostly for the i386 architecture.  On many
>      other architectures it does not exist or will  always  re‐
>      turn an error.
>
> Is this still true?
>
> Another issue:
>
>      EIO    (on PowerPC) This call is not supported.
>
> Is this really true?  Where this is not supported, I expect ENOSYS.

I'll let others answer these.

> And yet another thing: should we document the parameters as being
> uintptr_t instead of unsigned long?  They are the same exact type
> always, AFAIK.  Or is there any system where they aren't?  If they are
> the same, uintptr_t will better document that they are addresses.

I suppose it depends on the architecture, but for x86 these are actually
supposed to be 16-bit integers.  I guess they are longs for generality
within syscall ABI constraints.

Re: ioperm(2): confusing terminology

[Alejandro Colomar]

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

Hi astian,

> Date: 2026-09-13 06:29:43+0000
> From: astian <astian@memeware.net>
>
> On 13 Sep 2026 00:24 +0200, Alejandro Colomar wrote:
> >> Date: 2026-09-12 22:00:57+0000
> >> From: astian <astian@memeware.net>
> >>
> >> ioperm(2) says:
> >>
> >>   int ioperm(unsigned long from, unsigned long num, int turn_on);
> >>
> >>   ioperm() sets the port access permission bits for the calling thread
> >>   for num bits starting from port address from.  If turn_on is nonzero,
> >>   then permission for the specified bits is enabled; otherwise it is
> >>   disabled. [...]
> >>
> >> The use of "bits" here is confusing/sloppy.
> >>
> >> ioperm is supposed to enable or disable permission to access IO ports
> >> for the calling thread.  In this API, the "permission bit" (singular) is
> >> really "turn_on": 0 to disable access, non-zero to enable.  However this
> >> description refers also "num bits starting from port address from" and
> >> "the specified bits".  That seems to suggest that IO ports somehow refer
> >> to "bits" and this API controls access permission to them, which is
> >> bewildering.
> >>
> >> Searching around I have seen that other versions of this manpage used to
> >> say "bytes" instead of "bits", which is only slightly less bewildering.
> >> Ports/addresses in the IO space refer neither to bits nor to bytes per
> >> se, they are an abstract interface, like a syscall number/index.
> >> (Architecturally, in some cases, these indices may in fact map to
> >> processor registers which may in fact be portions of a contiguous
> >> internal memory, so in some cases one could correctly say that the ports
> >> refer to "bytes" in such memory, but this is obviously all very
> >> low-level and microarchitecture-specific.  I think being aware of such
> >> details actually makes this description more confusing.)
> >>
> >> Apparently the reason for this confusing description is that for Linux
> >> ioperm is a syscall and the kernel implements this syscall using a
> >> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> >> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> >>
> >> Thus "num bits starting from port address from" actually refers to the
> >> bits of that bitmap: the bits [from, from+num) are set according to
> >> turn_on.
> >>
> >> This kind of implicit reference to implementation details is wicked.
> 
> To complete the picture: this is not a mere Linux-specific
> implementation detail.  At least for x86 (IA-32) it is inherited from
> the processor architecture: the port permission bitmap is linked from
> the structure pointed to by the "Task State Segment" (TSS) and checked
> by the processor.
> 
> It is still an implicit reference to an implementation detail.  I think
> not mentioning this bits-and-bitmaps business is better but
> alternatively the reference should be made explicit and the kernel
> bitmap should be mentioned (and for x86 perhaps also the TSS).
> 
> >> Suggested change:
> >>
> >>   ioperm() sets the calling thread's access permission for num ports
> >>   starting from port address from.  If turn_on is nonzero, then
> >>   permission for the specified ports is enabled; otherwise it is
> >>   disabled. [...]
> >
> > Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
> > I write it?  (I don't mind; just asking in case you want to do it.)
> >
> >> PS: Oh, also, maybe the title should say "set input/output port
> >> permissions" instead of "set port input/output permissions".
> >
> > Same here.
> 
> Sorry, I've never written *roff before

I've never written roff(7) myself, but luckily, man(7) is much simpler
than roff(7).

> and I don't think I want to spend
> my time learning that... although, I might be able do this by just
> blindly replacing words without touching the escapes...

Indeed, that's how I learnt man(7).  Replacing words blindly is quite
easier than it seems.  I was also scared the first time I wanted to fix
a bug in a manual page, but I found it was easier than I thought.

> Which bring up the question, why not moving to a less hairy source
> format?

This question comes up every now and then.  TL;DR: other formats are
worse.

man(7) is pretty simple, and easy to learn exactly by editing words
blindly.  There are very few macros, and their behavior is trivial once
you use them a few times.

One thing that is very important is that we use semantic newlines.
That discards .md and .rst, since they are meant to be written with
paragraphs as they'd be read by humans.  mdoc(7) is more complex than
man(7), and thus we don't want that.  There are other formats, also
inappropriate, for the same or other reasons.

A summary that will serve for 95%+ of the text written in manual pages:

		.SH section heading
		.SS sub section
		.B bold
		.I italics

	Alternating per word (spaces removed):
		.BI bold italics
		.IB italics bold
		.BR bold roman
		.RB roman bold
		.IR italics roman
		.RI roman italics
	(roman means normal)

	paragraph separator:
		.P
	Indented paragraph:
		.IP
	Tagged paragraph:
		.TP
		tag

	Examples:
		.EX
		this is an example (monospace, no fill)
		.EE

> > BTW, the manual page also says:
> >
> >      This  call  is  mostly for the i386 architecture.  On many
> >      other architectures it does not exist or will  always  re‐
> >      turn an error.
> >
> > Is this still true?
> >
> > Another issue:
> >
> >      EIO    (on PowerPC) This call is not supported.
> >
> > Is this really true?  Where this is not supported, I expect ENOSYS.
> 
> I'll let others answer these.
> 
> > And yet another thing: should we document the parameters as being
> > uintptr_t instead of unsigned long?  They are the same exact type
> > always, AFAIK.  Or is there any system where they aren't?  If they are
> > the same, uintptr_t will better document that they are addresses.
> 
> I suppose it depends on the architecture, but for x86 these are actually
> supposed to be 16-bit integers.  I guess they are longs for generality
> within syscall ABI constraints.

Ahh, sorry, it's a port address, not an address.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Markdown as a "less hairy" source format for man pages (was: ioperm(2): confusing terminology)

[G. Branden Robinson]

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

Hi Alex,

At 2026-09-14T14:56:21+0200, Alejandro Colomar wrote:
> > Date: 2026-09-13 06:29:43+0000
> > From: astian <astian@memeware.net>
> > Sorry, I've never written *roff before
> 
> I've never written roff(7) myself, but luckily, man(7) is much simpler
> than roff(7).
> 
> > and I don't think I want to spend my time learning that... although,
> > I might be able do this by just blindly replacing words without
> > touching the escapes...
> 
> Indeed, that's how I learnt man(7).  Replacing words blindly is quite
> easier than it seems.  I was also scared the first time I wanted to
> fix a bug in a manual page, but I found it was easier than I thought.
> 
> > Which bring up the question, why not moving to a less hairy source
> > format?
> 
> This question comes up every now and then.  TL;DR: other formats are
> worse.
> 
> man(7) is pretty simple, and easy to learn exactly by editing words
> blindly.  There are very few macros, and their behavior is trivial
> once you use them a few times.
> 
> One thing that is very important is that we use semantic newlines.
> That discards .md and .rst, since they are meant to be written with
> paragraphs as they'd be read by humans.  mdoc(7) is more complex than
> man(7), and thus we don't want that.  There are other formats, also
> inappropriate, for the same or other reasons.
[...]

Another reason to not underestimate the "hairiness" of "plain text"
markup languages relative to man(7) is revealed by the sorts of trouble
that people get into with at least some of its dialects.

Here's an example from the util-linux project, which maintains its man
pages in AsciiDoc.

commit 36e1fb5802c0948f13ba0ec4ac68c94cb24856db
Author: Thomas Weißschuh <thomas@t-8ch.de>
Date:   Mon Apr 27 15:24:47 2026 +0200

    lastlog2: (man) fix example syntax

    The examples are not using the right syntax for literal blocks,
    leading to errors from asciidoctor.

    Use the correct syntax.

    Fixes: cd112d860bf6 ("lastlog2: add --journal option to manage SQLite journal mode")
    Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>

diff --git a/misc-utils/lastlog2.8.adoc b/misc-utils/lastlog2.8.adoc
index b8fcb055c..20a971242 100644
--- a/misc-utils/lastlog2.8.adoc
+++ b/misc-utils/lastlog2.8.adoc
@@ -91,19 +91,19 @@
 == EXAMPLES

 Display the current journal mode:
-----
+....
 lastlog2 -j
-----
+....

 Enable WAL mode for better concurrency (recommended for high-traffic servers):
-----
+....
 lastlog2 -j WAL
-----
+....

 Switch back to the default DELETE mode:
-----
+....
 lastlog2 -j DELETE
-----
+....

 == FILES
---end snip; there was much more in the same vein after this---

Not long ago I diagnosed our industry's collective, and persistent,
refusal to believe that writing worthwhile documentation could ever be a
more demanding task than the simplest computer program one can code.

https://lore.kernel.org/linux-man/20260710195854.ud4riftmhrfzu54d@illithid/

Regards,
Branden

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