Re: cd command, chdir syscall, shell behavour

[Ingo Schwarze]

Hi Edgar,

Edgar Pettijohn wrote on Sat, Jun 29, 2019 at 07:48:35PM -0500:
> Ingo Schwarze wrote:

>> If you want to search for a manual page, use man(1).
>> If you want to search for packages, use pkglocate(1).

> I don't think this would be needed on openbsd as the default
> install has everything you need for a basic system and it's easy
> to add additional packages. However, as I learned when I set up
> a Debian box for my son to play Minecraft it didn't. So it was
> kinda nice when I typed ifconfig it informed me what package to
> install

That argument doesn't really apply even to Debian.
Just like i said

  If you want to search for packages, use pkglocate(1).

for OpenBSD, you would say

  $ apt-cache search ifconfig

on Debian.  Different systems have different tools, but the concept
that each tool should focus on its own job still applies.

Besides, ip(8) was probably already installed and likely good enough
for your job.

> and I eventually got everything working no thanks to the
> piss poor manual pages provided.

And that even though in the Linux world, few systems insist that
everything should have a manual page as much as Debian does...

Yours,
  Ingo

Re: cd command, chdir syscall, shell behavour

[Ingo Schwarze]

Hi Ian,

ropers wrote on Sun, Jun 30, 2019 at 02:18:56PM +0200:

> In bash, `help` is a shell builtin and does do something, though IMO,
> the something that it does isn't initially as helpful as OpenBSD's
> help(1), especially to newbies. [1]

Yes.  When a user types "help", it is unlikely they are confused
only about shell builtins (or even about the shell at large), but
it sounds more like they need getting started with the OS as a
whole.

> However, what it does do, i.e.
> * print a list of bash builtins in response to `help`, or
> * print bash builtin-specific help in response to `help [builtin]`
> could well be helpful later and relates to what we discussed earlier.
> Is man(1) plus info(1) plus bash's help some kind of triple
> book-keeping or wheel-reinvention?

More like quadruple because there is also the usage message.

But yes, that having a one- or two-line usage message on the one
hand and a complete and concise manual page on the other hand, and
no third copy of the same, is the current official OpenBSD position
because the information isn't really that hard to find in the manual
page, and a third copy would cause additional maintenance effort
and risk getting outdated.

All the same, developers occasionally discuss whether exceptions
of having -h or --help options for a few unusually complicated
programs might make sense (for example right now on tech@), but so
far, it was usually rejected.

> Perhaps, but in terms of convenience, bash's `help` and `help [builtin]`
> are stiff competition to [...] `man -k Ic,Nm=[term]` and `man -O
> tag=[term]`.

Except that features like `help` and `help [builtin]` work differently
for each and every program, so you can't really get used to them,
neither to how to call them nor to which usually incomplete selection
of information they might throw at you, whereas semantic tags work
in a general and uniform way, and not only for .Ic, which is just
one of many examples.

> footnote:
> [1] This also means that if an OpenBSD sysadmin tries to be "helpful
> to newbies" by installing the bash they're maybe used to, they will by
> default clobber access to OpenBSD's excellent help(1), and it would
> take extra care to re-enable that and to then figure out a nice way to
> still provide access to bash's builtin help too... aaargh! Maybe bash
> on OpenBSD isn't the best choice really.

Indeed, in particular not as a login shell.

On the other hand, if a user explicitly types "bash", they get what
they ask for, and there is nothing wrong with that.

Yours,
  Ingo

Re: cd command, chdir syscall, shell behavour

[ropers]

Oops, I just mistakenly attributed Ingo's earlier reply to Edgar.
Apologies to both, and thanks very much for the help.

Ian

On 30/06/2019, ropers  wrote:
> On 30/06/2019, Edgar Pettijohn  wrote:
 Then you need to say (...snip; see earlier email...)
>
> Thank you. That contained several useful hints I hadn't even figured
> out I could look for there, although this too seems obvious in
> retrospect. Maybe I'm not thinking about these things carefully enough
> in advance. :)
>
>>> This is perfectly fine, exactly as it should be:
>>>
>>>   schwarze@isnote $ man bash
>>>   man: No entry for bash in the manual.
>>>   schwarze@isnote $ pkglocate bin/bash | head -n1
>>>   bash-5.0.7p0:shells/bash:/usr/local/bin/bash
>>>
>>> > To end on a positive: Can I add how much I appreciate that OpenBSD
>>> > hard-links help(1) to man(1),
>>>
>>> Heh; deraadt@ did that on Sep 14, 1998 for OpenBSD 2.4 ...
>>>
>>> > and that man will default to `man help` when called as help?
>>>
>>> and aaron@ added the help(1) manual page on Oct 18, 1999
>>> for OpenBSD 2.6.
>>>
>>> > This elegant way of having OpenBSD respond to `help` is really
>>> > n00b-friendly.
>>>
>>> And yet, even among those tiny innovations that are somehow neat,
>>> not all get picked up elsewhere:
>>>
>>>   https://man.openbsd.org/FreeBSD-12.0/help
>>>   https://man.openbsd.org/NetBSD-8.0/help
>>>   https://man.openbsd.org/Linux-5.01/help
>
> In bash, `help` is a shell builtin and does do something, though IMO,
> the something that it does isn't initially as helpful as OpenBSD's
> help(1), especially to newbies. [1]
>
> However, what it does do, i.e.
> * print a list of bash builtins in response to `help`, or
> * print bash builtin-specific help in response to `help [builtin]`
> could well be helpful later and relates to what we discussed earlier.
> Is man(1) plus info(1) plus bash's help some kind of triple
> book-keeping or wheel-reinvention? Perhaps, but in terms of
> convenience, bash's `help` and `help [builtin]` are stiff competition
> to Edgar's earlier hints of `man -k Ic,Nm=[term]` and `man -O
> tag=[term]`.
> Don't get me wrong; I'm VERY grateful for the hints, and I don't think
> I have or know of an ideal solution. All the same, I think this is
> still an area where considerable possibility for user confusion yet
> abounds.
>
> Ian
>
> footnote:
> [1] This also means that if an OpenBSD sysadmin tries to be "helpful
> to newbies" by installing the bash they're maybe used to, they will by
> default clobber access to OpenBSD's excellent help(1), and it would
> take extra care to re-enable that and to then figure out a nice way to
> still provide access to bash's builtin help too... aaargh! Maybe bash
> on OpenBSD isn't the best choice really.
>

Re: cd command, chdir syscall, shell behavour

[ropers]

On 30/06/2019, Edgar Pettijohn  wrote:
>>> Then you need to say (...snip; see earlier email...)

Thank you. That contained several useful hints I hadn't even figured
out I could look for there, although this too seems obvious in
retrospect. Maybe I'm not thinking about these things carefully enough
in advance. :)

>> This is perfectly fine, exactly as it should be:
>>
>>   schwarze@isnote $ man bash
>>   man: No entry for bash in the manual.
>>   schwarze@isnote $ pkglocate bin/bash | head -n1
>>   bash-5.0.7p0:shells/bash:/usr/local/bin/bash
>>
>> > To end on a positive: Can I add how much I appreciate that OpenBSD
>> > hard-links help(1) to man(1),
>>
>> Heh; deraadt@ did that on Sep 14, 1998 for OpenBSD 2.4 ...
>>
>> > and that man will default to `man help` when called as help?
>>
>> and aaron@ added the help(1) manual page on Oct 18, 1999
>> for OpenBSD 2.6.
>>
>> > This elegant way of having OpenBSD respond to `help` is really
>> > n00b-friendly.
>>
>> And yet, even among those tiny innovations that are somehow neat,
>> not all get picked up elsewhere:
>>
>>   https://man.openbsd.org/FreeBSD-12.0/help
>>   https://man.openbsd.org/NetBSD-8.0/help
>>   https://man.openbsd.org/Linux-5.01/help

In bash, `help` is a shell builtin and does do something, though IMO,
the something that it does isn't initially as helpful as OpenBSD's
help(1), especially to newbies. [1]

However, what it does do, i.e.
* print a list of bash builtins in response to `help`, or
* print bash builtin-specific help in response to `help [builtin]`
could well be helpful later and relates to what we discussed earlier.
Is man(1) plus info(1) plus bash's help some kind of triple
book-keeping or wheel-reinvention? Perhaps, but in terms of
convenience, bash's `help` and `help [builtin]` are stiff competition
to Edgar's earlier hints of `man -k Ic,Nm=[term]` and `man -O
tag=[term]`.
Don't get me wrong; I'm VERY grateful for the hints, and I don't think
I have or know of an ideal solution. All the same, I think this is
still an area where considerable possibility for user confusion yet
abounds.

Ian

footnote:
[1] This also means that if an OpenBSD sysadmin tries to be "helpful
to newbies" by installing the bash they're maybe used to, they will by
default clobber access to OpenBSD's excellent help(1), and it would
take extra care to re-enable that and to then figure out a nice way to
still provide access to bash's builtin help too... aaargh! Maybe bash
on OpenBSD isn't the best choice really.

Re: cd command, chdir syscall, shell behavour

[Janne Johansson]

Den lör 29 juni 2019 kl 22:42 skrev ropers :

> Anyway, in an ideal world, typing man  would always show the man
> page
> actually relevant to what the box would do if the user typed  at
> the
> prompt. I don't know how this could be solved though;


and how would
$ unset PATH ; man cc
behave? By showing nothing now that you can no longer find a c compiler?
or
$ PATH=$HOME/bin  man cc
should not show manpage for system compiler but dig out that local cc you
built in your home dir long time ago?
There is a rabbit hole to fall into if you want docs to change depending on
your definition of "relevant" in the sentence above.

-- 
May the most significant bit of your life be positive.

Re: cd command, chdir syscall, shell behavour

[Edgar Pettijohn]

On Jun 29, 2019 5:50 PM, Ingo Schwarze  wrote:
>
> Hi Ian,
>
> ropers wrote on Sat, Jun 29, 2019 at 10:40:30PM +0200:
>
> > This relates to a long-standing annoyance: When I do `man kill` for
> > example, the manpage shown is for code that won't be what runs when I
> > do `kill `.
> > I suppose the general case is that there can be discrepancies between
> >
> >>> $ which kill
> >>> /bin/kill
> >>> $ type kill
> >>> kill is a shell builtin
> >
> > and perhaps `man kill` too (kill is just an example; the issue
> > generalises).
> > As much as this looks like a problem that wants solving, it's such a
> > long-standing and fundamental issue that I'm not sure what can be
> > done. Is there any sense in adding some checks to man(1) to ensure the
> > "wrong" information is not displayed?
>
> It isn't the wrong information.  The command
>
>   $ man kill
>
> means:
>
>   Show me the manual page with the name "kill".
>
> Clearly, that will be kill(1) and not ksh(1).
>
> If what you mean is:
>
>   Show me the manual pages documenting "kill", no matter whether
>   as a stand-alone command or an internal command built-in to another
>   program.
>
> Then you need to say:
>
>   $ man -k Ic,Nm=kill
>
> or something similar.
>
> > An added complication: When users are looking at the respective
> > sections for builtins in `man sh` vs `man ksh`, it may not always be
> > clear which description and behaviour would actually apply.
> > It's also very cumbersome to jump to the correct section e.g. in `man
> > ksh`, even if the user already knows what kind of command and
> > documentation to look for (which is half the battle). One way I
> > sometimes do that is:
> > >> $ man ksh
> > >> G?The following describes/
> > This obviously isn't ideal, but I have not found any applicable
> > shortcuts. Would it be possible to add some way to make it easier to
> > accomplish the task "show me the documentation of builtin  in man
> > ksh"?
>
> What's wrong with:
>
>   $ man -O tag=kill ksh
>
> It's documented in
>
>   $ man -O tag=tag mandoc
>
> Alternatively, type this:
>
>   man ksh:tkill
>
> As documented here:
>
>   $ man -O tag=MANPAGER man
>
> > Anyway, in an ideal world, typing man  would always show the
> > man page actually relevant to what the box would do if the user typed
> >  at the prompt.
>
> No.  That's not how man(1) is defined.  It's
>
>   usage: man [-acfhklw] [-C file] [-M path] [-m path] [-S subsection]
>  [[-s] section] name ...
>
> not
>
>   usage: man ... command ...
>
> Besides, how man(1) searches for the "name" should absolutely not
> depend on the shell the user is currently running.
>
> What next?  When you run
>
>   $ perl -e 'system qw(man kill)'
>
> you want to see the same as with:
>
>   $ perldoc -f kill
>
> > I don't know how this could be solved though; I'm just noticing that
> > there's much inconsistency and considerable possibility for user
> > confusion in that area.
>
> No man(1) begaves quite consistently and predictably.  You are
> merely confused about what the man(1) "name" argument is and how
> to search for internal commands of arbitrary programs instead.
>
> > As another aside:
> > On Ubuntu (and probably Debian), when the user types a command name
> > that does not correspond to any program actually installed, but that
> > *does* correspond to an executable present in a .deb package present
> > in currently configured repositories, the system will recommend that
> > package (sometimes several packages) and helpfully print what the user
> > would have to type to install said package(s).
>
> How revolting.  That's very contrary to the spirit of Unix.
> We certainly don't want to copy that.  No program should attempt
> to implement its very own partial solution for every *other* task
> under the sun, but instead focus on doiing its own task well.
>
> If you want to search for a manual page, use man(1).
> If you want to search for packages, use pkglocate(1).
>

I don't think this would be needed on openbsd as the default install has 
everything you need for a basic system and it's easy to add additional 
packages. However, as I learned when I set up a Debian box for my son to play 
Minecraft it didn't. So it was kinda nice when I typed ifconfig it informed me 
what package to install and I eventually got everything working no thanks to 
the piss poor manual pages provided.

Edgar

> This is perfectly fine, exactly as it should be:
>
>   schwarze@isnote $ man bash   
>   man: No entry for bash in the manual.
>   schwarze@isnote $ pkglocate bin/bash | head -n1
>   bash-5.0.7p0:shells/bash:/usr/local/bin/bash
>
> > To end on a positive: Can I add how much I appreciate that OpenBSD
> > hard-links help(1) to man(1),
>
> Heh; deraadt@ did that on Sep 14, 1998 for OpenBSD 2.4 ...
>
> > and that man will default to `man help` when called as help?
>
> and aaron@ added the help(1) manual page on Oct 18, 1999
> for OpenBSD 2.6.
>
> > This elegant way of having OpenBSD respond to 

Re: cd command, chdir syscall, shell behavour

[Ingo Schwarze]

Hi Ian,

ropers wrote on Sat, Jun 29, 2019 at 10:40:30PM +0200:

> This relates to a long-standing annoyance: When I do `man kill` for
> example, the manpage shown is for code that won't be what runs when I
> do `kill `.
> I suppose the general case is that there can be discrepancies between
>
>>> $ which kill
>>> /bin/kill
>>> $ type kill
>>> kill is a shell builtin
>
> and perhaps `man kill` too (kill is just an example; the issue
> generalises).
> As much as this looks like a problem that wants solving, it's such a
> long-standing and fundamental issue that I'm not sure what can be
> done. Is there any sense in adding some checks to man(1) to ensure the
> "wrong" information is not displayed?

It isn't the wrong information.  The command

  $ man kill

means:

  Show me the manual page with the name "kill".

Clearly, that will be kill(1) and not ksh(1).

If what you mean is:

  Show me the manual pages documenting "kill", no matter whether
  as a stand-alone command or an internal command built-in to another
  program.

Then you need to say:

  $ man -k Ic,Nm=kill

or something similar.

> An added complication: When users are looking at the respective
> sections for builtins in `man sh` vs `man ksh`, it may not always be
> clear which description and behaviour would actually apply.
> It's also very cumbersome to jump to the correct section e.g. in `man
> ksh`, even if the user already knows what kind of command and
> documentation to look for (which is half the battle). One way I
> sometimes do that is:
> >> $ man ksh
> >> G?The following describes/
> This obviously isn't ideal, but I have not found any applicable
> shortcuts. Would it be possible to add some way to make it easier to
> accomplish the task "show me the documentation of builtin  in man
> ksh"?

What's wrong with:

  $ man -O tag=kill ksh

It's documented in

  $ man -O tag=tag mandoc

Alternatively, type this:

  man ksh:tkill

As documented here:

  $ man -O tag=MANPAGER man

> Anyway, in an ideal world, typing man  would always show the
> man page actually relevant to what the box would do if the user typed
>  at the prompt.

No.  That's not how man(1) is defined.  It's

  usage: man [-acfhklw] [-C file] [-M path] [-m path] [-S subsection]
 [[-s] section] name ...

not

  usage: man ... command ...

Besides, how man(1) searches for the "name" should absolutely not
depend on the shell the user is currently running.

What next?  When you run

  $ perl -e 'system qw(man kill)'

you want to see the same as with:

  $ perldoc -f kill

> I don't know how this could be solved though; I'm just noticing that
> there's much inconsistency and considerable possibility for user
> confusion in that area.

No man(1) begaves quite consistently and predictably.  You are
merely confused about what the man(1) "name" argument is and how
to search for internal commands of arbitrary programs instead.

> As another aside:
> On Ubuntu (and probably Debian), when the user types a command name
> that does not correspond to any program actually installed, but that
> *does* correspond to an executable present in a .deb package present
> in currently configured repositories, the system will recommend that
> package (sometimes several packages) and helpfully print what the user
> would have to type to install said package(s).

How revolting.  That's very contrary to the spirit of Unix.
We certainly don't want to copy that.  No program should attempt
to implement its very own partial solution for every *other* task
under the sun, but instead focus on doiing its own task well.

If you want to search for a manual page, use man(1).
If you want to search for packages, use pkglocate(1).

This is perfectly fine, exactly as it should be:

  schwarze@isnote $ man bash   
  man: No entry for bash in the manual.
  schwarze@isnote $ pkglocate bin/bash | head -n1
  bash-5.0.7p0:shells/bash:/usr/local/bin/bash

> To end on a positive: Can I add how much I appreciate that OpenBSD
> hard-links help(1) to man(1),

Heh; deraadt@ did that on Sep 14, 1998 for OpenBSD 2.4 ...

> and that man will default to `man help` when called as help?

and aaron@ added the help(1) manual page on Oct 18, 1999
for OpenBSD 2.6.

> This elegant way of having OpenBSD respond to `help` is really
> n00b-friendly.

And yet, even among those tiny innovations that are somehow neat,
not all get picked up elsewhere:

  https://man.openbsd.org/FreeBSD-12.0/help
  https://man.openbsd.org/NetBSD-8.0/help
  https://man.openbsd.org/Linux-5.01/help

Yours,
  Ingo

Re: cd command, chdir syscall, shell behavour

[ropers]

On 28/06/2019, Ingo Schwarze <> wrote:
(...) while the fact that the cwd is a property
> of each process is actually fairly obvious in the first place.
> What else could it possibly be, in a multi-user system?

Fair enough; I suppose it's one of these things that once you know
them, they're obvious, and anything else seems unimaginable. ;)
But to imagine something else: Things could have been designed for the
shell to run in /bin (its *own* cwd) while *separately* keeping state
of a user- and program-cwd, which is what I meant when I talked about
nannying and chaperoning programs, etc.
However, there is a minimalist and very Unix-like elegance to the
actual choice of just using the working directory of the current shell
execution environment for that end. I do admire it, and it does make
permissions that much clearer. I had just never thought about it
before, though it seems so obvious in retrospect.

The only thing that now feels less intuitively clear is that there
apparently still is a need to have traverse permissions all the way
down, as mentioned here for example:

>> On the lower level, this particular permission in stat.h standard Unix 
>> library
>> is defined as
>>S_IXUSR
>>Execute/search permission, owner.
>> (...)
>> The reason behind that lies in the POSIX definition of EACCES:
>>[EACCES] Permission bits of the file mode do not permit the requested
>> access, or search permission is denied on a component of the path prefix
This would suggest path resolution back from the directory root with
every chdir() call, no? Now that I think about it, I'm not entirely
sure when traverse permissions (for "upper"/path prefix directories)
really come into play.
But this is really more of a "I need to learn this" issue and less of
a "can OpenBSD's man pages be improved here" issue.


Ingo Schwarze <> wrote:
> we don't write separate manual pages for shell builtins.
>
> It was discussed internally whether the chdir(2), getcwd(3),
> pwd(1), and ksh(1) manual pages can be improved to make it more
> explicit that the current working directory is a process property.
>
> But the conclusion was that introducing wording to that effect risks
> causing other ambiguities, (...)
>
> So the manual pages remain unchanged.

This relates to a long-standing annoyance: When I do `man kill` for
example, the manpage shown is for code that won't be what runs when I
do `kill `.
I suppose the general case is that there can be discrepancies between
>> $ which kill
>> /bin/kill
>> $ type kill
>> kill is a shell builtin
and perhaps `man kill` too (kill is just an example; the issue generalises).
As much as this looks like a problem that wants solving, it's such a
long-standing and fundamental issue that I'm not sure what can be
done. Is there any sense in adding some checks to man(1) to ensure the
"wrong" information is not displayed?
An added complication: When users are looking at the respective
sections for builtins in `man sh` vs `man ksh`, it may not always be
clear which description and behaviour would actually apply.
It's also very cumbersome to jump to the correct section e.g. in `man
ksh`, even if the user already knows what kind of command and
documentation to look for (which is half the battle). One way I
sometimes do that is:
>> $ man ksh
>> G?The following describes/
This obviously isn't ideal, but I have not found any applicable
shortcuts. Would it be possible to add some way to make it easier to
accomplish the task "show me the documentation of builtin  in man
ksh"?


|Side note:
|The util-linux whereis(1) will, as per `man -k whereis`,
|"locate the binary, source, and manual page files for a command",
|while OpenBSD's whereis(1) will "locate programs", noting that
|>> The whereis command first appeared in 2BSD, but the original version was
|>> legally tainted and was not included as part of the 4.4BSD release, such
|>> that most of the original functionality was lost.
|cf. 
|FreeBSD has a version that
|>> re-implements the historical functionality that was lost in 4.4BSD.
|cf. 
|They've apparently had those features back since FreeBSD 2.2.1 (April, 1997),
|which would have been not long after those features were removed. They seem
|to have rewritten their whereis(1) in 2002:
|
|How suitable any of this might be for OpenBSD I'm not in a position to say.


Anyway, in an ideal world, typing man  would always show the man page
actually relevant to what the box would do if the user typed  at the
prompt. I don't know how this could be solved though; I'm just noticing that
there's much inconsistency and considerable possibility for user confusion in
that area.


|As another aside:
|On Ubuntu (and probably Debian), when the user types a 

Re: cd command, chdir syscall, shell behavour

[Ingo Schwarze]

Hi,

ropers wrote on Sun, Jun 23, 2019 at 05:35:06PM +0200:

> This is made slightly clearer by the language used in the POSIX spec
> and on a bunch of other, non-OpenBSD man pages derived from it:

In general, we don't like the style POSIX describes things all that
much.  It may be the adequate level of formalism required in a
specification, but many aspects feel overly technical for a manual,
and then all those "shall" and "must" which feel unfriendly in a
manual page...

>>> The cd utility shall change the working directory of the current
>>> shell execution environment...
> http://pubs.opengroup.org/onlinepubs/9699919799.2013edition/utilities/cd.html

> If that's all correct, then would it make sense to retrofit any of the
> above enlightening language (from 8.4 or POSIX) into OpenBSD's sh or
> ksh man pages? I don't suppose a separate cd(1) man page makes sense?
> (There's cd(4), but that's different.)

No, we don't write separate manual pages for shell builtins.

It was discussed internally whether the chdir(2), getcwd(3),
pwd(1), and ksh(1) manual pages can be improved to make it more
explicit that the current working directory is a process property.

But the conclusion was that introducing wording to that effect risks
causing other ambiguities, while the fact that the cwd is a property
of each process is actually fairly obvious in the first place.
What else could it possibly be, in a multi-user system?

So the manual pages remain unchanged.

Yours,
  Ingo

[OT][man and basic comprehension][amateur hour] cd command, chdir syscall, shell behavour (was: The su manual doesn't mention use root account by default)

[ropers]

Ingo Schwarze wrote:
> su(I) goes back all the way to v1: (...) It wasn't in v0 PDP-7 UNIX though:
> https://www.tuhs.org/Archive/Distributions/Research/McIlroy_v0/UnixEditionZero.txt

>From that text file:
>> 8.4 chdir -- change directories
>>
>> To change the current directory, use
>>
>>   chdir dirname
>>
>> This command is the only one that does not reside in directory
>> "/bin"; instead it is part of the Shell. The reason is
>> interesting. Recall that each ordinary command is executed as a
>> separate process created by the Shell. If the system’s chdir
>> primitive were executed in such a process, it would have essentially
>> no effect, since the process would terminate instantly
>> without affecting the current directory of the Shell process and
>> its subsequent offSpring.[sic] The Shell itself recognizes the chdir
>> command and calls the system to change directories without
>> creating a new process.

Whoa.

This probably isn't news to most people here, but that just blew my
mind a little.
Please CORRECT ME if any of the following is still wrong:

I've--embarrassingly--only realised now that the shell is a decidedly
NON-special program in terms of what it does when the cd (formerly
chdir) command is issued at its prompt. Keeping state in remembering
your current working directory isn't so much something the shell does
for, to and on behalf of users and programs, it's actually something
the shell does TO ITSELF, by simply calling the chdir(2) syscall like
any other program would. The shell doesn't chaperone or nanny *you*,
it transplants *itself*. Effectively, the shell then runs *in* the new
current directory, and that's why the question whether to cd or not to
cd into a directory is controlled by execute permissions.

Much elegant.
Very Unix.
Wow.

This is made slightly clearer by the language used in the POSIX spec
and on a bunch of other, non-OpenBSD man pages derived from it:

>> The cd utility shall change the working directory of the current shell 
>> execution environment...


If that's all correct, then would it make sense to retrofit any of the
above enlightening language (from 8.4 or POSIX) into OpenBSD's sh or
ksh man pages? I don't suppose a separate cd(1) man page makes sense?
(There's cd(4), but that's different.)

Ian