Hello Amelia,
Amelia A Lewis wrote on Sat, Aug 09, 2025 at 02:31:40PM -0400:
> On Sat, 09 Aug 2025 12:55:28 +0000, jbra...@dismail.de wrote:
>> August 8, 2025 at 5:24 PM, "Dan" wrote:
>>> Try it yourself, pls
>>> wiz# man /usr/lib/libform.so.6.0
>> I'm lost....what does that command do?
> Best guess: man defaults to -l if given a bare filename
Not exactly true.
As documented in the first sentence of the man(1) manual, man(1)
defaults to interpreting its arguments as manual page names,
not as file names. So if you say "man /usr/lib/libform.so.6.0",
man(1) first searches the manual page databases for a manual
page declaring "/usr/lib/libform.so.6.0" as one of its manual
page names. That fails because no page exists having such a name.
If you want, you can create one:
$ mkdir -p man/man1
$ cat > man/man1/mypage.1
.Dd August 15, 2025
.Dt MYPAGE 1
.Os
.Sh NAME
.Nm /usr/lib/libform.so.6.0
.Nd test page
.Sh DESCRIPTION
Hello world!
$ makewhatis man
$ man -Mman -w mypage
/home/schwarze/man/man1/mypage.1
$ man -Mman -w /usr/lib/libform.so.6.0
/home/schwarze/man/man1/mypage.1
$ man -Mman -Tascii -Owidth=60 -c /usr/lib/libform.so.6.0 | grep -v '^$'
MYPAGE(1) General Commands Manual MYPAGE(1)
NAME
/usr/lib/libform.so.6.0 - test page
DESCRIPTION
Hello world!
OpenBSD 7.7 August 15, 2025 MYPAGE(1)
Only after the documented name lookup fails, man(1) resorts to a
file system search, looking for files with names similar to
/usr/share/man/man[1-9]/usr/lib/libform.so.6.0.[1-9]
/usr/share/man/cat[1-9]/usr/lib/libform.so.6.0.0
Creating such files is left as an exercise to the user; in a sanely
configured system, such files do not exist either, so the file
system fallback search fails, too.
At this point, if the requested manual page name does not contain
a slash, man(1) exits with an error message:
$ man usr_lib_libform.so.6.0
man: No entry for usr_lib_libform.so.6.0 in the manual.
Only if the requested manual page name contains a alash, man(1) does
a stat(2) to see whether a file by that name exists. If it does, only
in this very particular case man(1) assumes that the user probably
meant "-l", but -l is certainly not the default.
Here is the commit message that introduced the compat feature:
/usr/src/usr.bin/mandoc/main.c revision 1.208
date: 2018/04/19 16:25:11; author: schwarze; lines: +57 -13
Compatibility with man-db:
In page name mode (= man(1) default mode), also try to interpret
names containing slashes as absolute or relative file names.
Missing feature reported by Nate Bargmann on <groff at gnu dot org>,
and the man-db maintainer Colin Watson <cjwatson at debian dot org>
explained to me how this is supposed to work.
> (man -l produces identical output),
Correct.
> so man mandoc, and we discover that if you
> pass garbage (binary content instead of a file containing mandoc
> instructions), what you get out is expected: it dumps it unprocessed
> to $PAGER.
Absolutely not.
With cat(1) and similar tools, you can totally screw up your terminal
when you dump a binary file there.
In contrast, man(1) is very careful to only produce valid, printable
ASCII output (or UTF-8 output, when you request that with -T or LC_CTYPE)
that cannot under any circumstances harm the terminal. Compare:
$ man -Tascii /usr/lib/libform.so.6.0 | sed 's/[ -~]//g' | hexdump -C
00000000 0a 0a 08 08 08 08 08 08 08 0a 0a 08 08 08 08 08 |................|
00000010 08 08 08 08 0a 0a 0a 0a 08 0a 0a 08 08 08 08 08 |................|
00000020 08 08 08 08 08 08 08 08 08 08 08 08 08 08 0a 08 |................|
00000030 0a 08 08 08 0a 08 08 08 08 08 0a 08 08 08 08 08 |................|
00000040 0a 08 08 08 08 08 08 08 08 08 08 08 0a 0a 08 08 |................|
00000050 08 08 08 0a 08 08 08 08 08 08 08 0a 08 08 08 0a |................|
00000060 08 0a 0a 0a 0a 0a 0a 0a 0a |.........|
$ cat /usr/lib/libform.so.6.0 | sed 's/[ -~]//g' | hexdump -C
[ long list of all kinds of control characters ]
Great care has been taken to make sure that mandoc handles any kind
of garbage input in a safe and reasonable manner and never fails or
refuses formatting. In very early versions of mandoc, it could
happen that for certain kinds of very invalid input, the parser
would abort with an error message, and no output of the rest of
the file would be shown. But those times are long gone, for
about a decade.
> To test: got a text file in $HOME? man $HOME/txtfilename. man
> -l $HOME/txtfilename. mandoc $HOME/txtfilename. This won't work with a
> barename, though ./ works fine.
>
> Ingo, would it be worth noting in man man, that if given a path (a
> 'name' containing one or more path separators), that it will assume you
> meant "look at this mandoc file over here"
That would be inaccurate. With mandoc(1), manual page names
can contain slashes - not sure how well other man(1) implementations
handle that, maybe not very well.
Explaining the full story (see above) and saying that after all
name searches fail, names containing slashes are also tried as file
names (but only as a fallback) would complicate the manual page
too much. The man(1) manual page is intentionally kept simple
because it's among the first pages new users are sent to.
Besides, we generally do not document misfeatures that are only
supported for compatibility with other implementations (in this
case man-db). Relying on this compatibility feature is definitely
not recommended. If -l is what you mean, then *please* do say -l.
Explaining that man-db, in some arcane corner cases, allows leaving
out the -l would just encourage users to become sloppy and type
ambiguous and unclear commands.
> [and if they meant "give me documentation on what's in this library
> here, I dunno how to strings(1)"
Just saying, try commands like
$ man -k Lb=libsndio
That won't work for libform though because the curses documentation
still uses the ancient man(7) language rather than the simpler,
more powerful, and more modern mdoc(7) language, so searching
for library names is not currently supported for curses libraries.
> just let them look at the binary slop until they get tired
> (well, some people can actually read that mess,
Errr, no. There is no binary slop in the mandoc output.
Those question marks you see on your screen are actual question
marks, indicating that invalid, unsafe bytes were found in the
input file and sanitized out. Check the man(1) output with
hexdump(1): There is a lot of ASCII 3f = '?' in there.
It might sound as if i were bashing you, but that's not my intention.
You actually understood significantly more than the other posters
in this thread and formulated a potentially useful question from
your partial understanding - even though the answer is no,
documenting these details is undesirable. New users don't need
it, and more experienced users shouldn't rely on it, either.
Yours,
Ingo
> so it might be useful
> during recovery that somehow ate everything from a-l* in bin or
> /usr/bin, improbable as that seems)]. It might actually already be
> there, mind, and I simply overlooked it. I was looking for things that
> would conceptually accept a pathname instead of a name, and skipping
> over most of the rest.
>
> Verification: note that output for an unmodified input is consistent
> for man /path/file.name, man -l /path/file.name, and considering the
> greater compactness of avoiding the pager, mandoc /path/file.name.
