fstat(1): Add EXAMPLES section

[fernape]

Summary

Add examples covering -f, -m and -p flags.

While here, extend the initial description paragraph to note that fstat(1) will
report on all opened files, belonging to processes the user has access to. The
current paragraph may lead to understand that you can get information on opened
files from processes belonging to other users.

Test Plan

• mandoc -Tlint clean
• igor clean
• aspell happy
• man ./fstat.1 renders the page properly

Note: a previous warning shows up, but I don't know how to fix it. Every thing I
try just generate more warnings :-)

mandoc: fstat.1:121:2: WARNING: missing -width in -tag list, using 6n: Bl -tag

[bjk]

You want to add -width jail to the .Bl that's giving a mandoc/lint error at present:

.Bl -tag -width jail -offset indent -compact

usr.bin/fstat/fstat.1

243 ↗

(On Diff #78750)

Technically this does something slightly different than what the description claims (one would need to narrow the match to just the CMD column, e.g., with awk(1)), though I don't think we need to fix it in order for the patch to be worth committing.

[fernape]

Fix warning in line 121 as suggested by bjk@

This shows a couple of warnings, but they are false positives:

fstat.1:122:repeated:... Sy [jail]
fstat.1:123:repeated:[jail] root directory
fstat.1:126:repeated:... Sy [root]
fstat.1:127:repeated:[root] inode

The resulting text makes sense and the so-called repetition is hard to avoid.

[fernape]

usr.bin/fstat/fstat.1

243 ↗

(On Diff #78750)

Technically this does something slightly different than what the description claims (one would need to narrow the match to just the CMD column, e.g., with awk(1)), though I don't think we need to fix it in order for the patch to be worth committing.

Yes, you are right, this filters lines containing fstat. The only cases I can think of in which we would not filter by fstat in the CMD column is if someone's user is fstat or if there is a mount point called fstat.

What if we had this?

Show all open files discarding lines containing fstat

The description would be accurate and I think most people will understand the intention in the example.

[danfe]

usr.bin/fstat/fstat.1

245 ↗

(On Diff #78764)

Could we perhaps use less-particular-person'al, more common John Doe usernames like alice, bob, or eva, if foo and bar are not userish enough for you?

On a larger scale, I'm afraid I don't really see how these outputs are useful as examples, as they rather decreases SNR of the manpage and make it longer than actually help.

Actual useful example would be e.g. which command switches should be used to emulate/mimic output of similar programs such as lsof(8) or fuser(1) which are typically used on other Unix-like systems. Just an idea.

[fernape]

usr.bin/fstat/fstat.1

245 ↗

(On Diff #78764)

Sure thing, I can s/fernape/alice for instance.

On the other matter, do you mean doing things like this? (Using alice)

$ fuser -fu .
.: 83075c(fernape) 26474c(fernape)  3035c(fernape)  3034c(fernape)  3033c(fernape)  2946c(fernape)  1932c(fernape)  1927c(fernape)  1488c(fernape)  1487c(fernape)  1486c(fernape)  1333c(fernape)  1332c(fernape)  1331c(fernape)  1312c(fernape)  1308c(fernape)  1299c(fernape)  1297c(fernape)  1296c(fernape)  1295c(fernape)  1294c(fernape)  1291c(fernape)  1285c(fernape)  1283c(fernape)  1280c(fernape)  1279c(fernape)  1278c(fernape)  1277c(fernape)  1229c(fernape)  1225c(fernape)  1212c(fernape)  1210c(fernape)

$ fstat . | awk '{printf "%d%s(%s) ",$3,$4,$1;} END{printf "\n"}'
0FD(USER) 82980wd(fernape) 82978wd(fernape) 26474wd(fernape) 3035wd(fernape) 3034wd(fernape) 3033wd(fernape) 2946wd(fernape) 1932wd(fernape) 1927wd(fernape) 1488wd(fernape) 1487wd(fernape) 1486wd(fernape) 1333wd(fernape) 1332wd(fernape) 1331wd(fernape) 1312wd(fernape) 1308wd(fernape) 1299wd(fernape) 1297wd(fernape) 1296wd(fernape) 1295wd(fernape) 1294wd(fernape) 1291wd(fernape) 1285wd(fernape) 1283wd(fernape) 1280wd(fernape) 1279wd(fernape) 1278wd(fernape) 1277wd(fernape) 1229wd(fernape) 1225wd(fernape) 1212wd(fernape) 1210wd(fernape)

[bjk]

usr.bin/fstat/fstat.1

243 ↗

(On Diff #78750)

I would not object to that phrasing. (I don't object to the original phrasing, either, of course.)

[fernape]

• In the first example, do proper process filtering as suggested by bjk@

Address suggestions by danfe@:

• Remove redundant example. Merge examples for -f, -m and -p
• Add examples mimicking fuser(1) and netstat(1)
• Use "alice" or "bob" in the examples
• Trim the output of most examples to make the section more compact

[fernape]

Also, I added the EXIT STATUS section. fstat has the standard behavior.

[fernape]

usr.bin/fstat/fstat.1

245 ↗

(On Diff #78764)

Outputs have been trimmed. The longest one is in the first example since if shows different types of files (jail, text, root, stdin, stdout...).

Let me know what you think,

Thanks!

243 ↗

(On Diff #78750)

I changed the example and use awk to do the filtering.

[danfe]

@fernape wrote:

On the other matter, do you mean doing things like this?

I didn't have any particular example in mind, just remembering that people often ask me what's the name of lsof(8)-like utility in FreeBSD. I'm fine with whatever conversions you might come up with. :-)

Regarding examples in manpages in general, I feel that adding too much of output is not particularly useful (to an extent that is can often be guessed or deduced from the source code), and readers are typically interested in various inputs they can feed the program to solve their everyday tasks.

[bcr]

I agree. Maybe you can shorten the examples to a few lines and indicate the rest with ... without loosing too much context?

[fernape]

As suggested by bcr@ and others shorten examples output:

• Restrict examples output to two lines plus ellipses except in two cases where I think it is better to leave some more context:
  • example 4 to show errors
  • last example to show a minimal list of processes

• Remove output for example 5 (number of pipes opened by firefox...).

• Remove END block in before-last example. It does not add useful information and makes the redered line exceed the 80 column limit.

Also note:

• Added EXIT STATUS (in previous update)

[gbe]

OK from manpages . Thanks for adding this example section to the manpage.

[fernape]

In D26949#609343, @gbe wrote:

OK from manpages . Thanks for adding this example section to the manpage.

Thank you all for the comments and suggestions.