10

For example,

[fakename]$ type echo
echo is a shell builtin

But man echo gives me the GNU coreutils version of echo. What's the easiest way to tell if the man page I'm looking at is the correct one, i.e the one for the utility I'd get if I directly invoked it?

Kusalananda
  • 333,661
extremeaxe5
  • 1,183

6 Answers6

5

You don't, really. Not without knowledge external to the man page.

In the case of echo (and printf, and test, ...), it's often a shell builtin, so you'll need to know that and read the shell's documentation. (And echo is notoriously different in different implementations, use printf instead.)

In most, if not all shells, you can find if something is a builtin with type command, e.g. type echo will print echo is a shell builtin. (type is specified by POSIX but e.g. fish supports it too, as non-POSIXy as it is.) In Bash, you'd then read man bash, the online documentation, or use the builtin command help (which is specific to Bash, and which you need to know exists).

Even if the command is not a builtin, it's possible that there are several commands with the same name, rename being a famous example (see Why is the rename utility on Debian/Ubuntu different than the one on other distributions, like CentOS?). Now, your OS should have the correct man page for the actually installed utility, and e.g. in Debian, the "alternatives" system updates the corresponding man pages also when the command alternatives are changed. But if you read an online man page, you'll need to be aware of it.

Many utilities have a command line option like --version which might tell you what implementation that command is. (But not nearly all utilities have it. I think it's a GNUism originally, so GNU utilities have it, as well as those that happened to copy the custom.) In the case of rename, it happens to work in telling two different implementations apart:

debian$ rename --version
/usr/bin/rename using File::Rename version 0.20
centos$ rename --version
rename (util-linux-ng 2.17.2)

Besides that, your system might have an alias or a function with the same name of a utility, usually to modify the behaviour of the utility. In that case, the defaults presented in a man page might not apply. Aliases for ls are common, as are aliases adding -i to rm or mv. But type foo would also tell you if foo is an alias or function.

ilkkachu
  • 138,973
  • 2
    The shell built-in commands doesn't support the --version option. – GAD3R Aug 05 '18 at 12:08
  • 2
    @GAD3R, yeah, and neither do the standard utilities on BSDs, or many other tools. For shell builtins, it's of course not necessary, since it's the shell's version that applies, so just go check $BASH_VERSION in case of Bash... And for other utilities, you need to know if they support that option, which you'd find from the man page, leading us back to the original question. :D – ilkkachu Aug 05 '18 at 12:15
1

If you want the manual for a built-in command, then you need to look at the manual of your shell. The command will be documented therein, along with all other built-in commands (or there will at least be a reference to where the documentation for builtins is to be found).

  • bash: man bash or help echo from an interactive bash shell.
  • zsh: man zsh (and after a bit of reading, man zshbuiltin)
  • fish: man fish (and after a bit of reading, help echo)

The manual that you get for man echo documents /bin/echo, i.e. the external echo command. This command is not what you would use when you use echo without an explicit path.

Kusalananda
  • 333,661
  • As mentioned in my answer, on a user friendly UNIX, you get the documentation for all test versions if you type man test. – schily Aug 05 '18 at 12:11
  • 1
    @schily I'd rather run my unfriendly Unix where I get specific info about exactly what I ask for :-) – Kusalananda Aug 05 '18 at 12:16
  • You do not seem to like useful answers :-( If you did have a look at the sample man page, you did write a more useful answer, – schily Aug 05 '18 at 12:18
  • @schily An answer does not become more useful by referring to manual that are not available on the target system. A Unix does not become "friendly" by documenting every conceivable version of every external utility. It becomes confusing. – Kusalananda Aug 15 '18 at 09:14
  • An answer cannot be called useful if it confuses the reader and the Linux man page for echo is not helpful as it informs about builtin echo versions at a location that most readers don't read. – schily Aug 15 '18 at 09:19
  • @schily The OP knows that the echo command is a built-in and asks where to get the correct information about built-in commands. The correct answer is to look at the shell's manual. In what way is this not useful? – Kusalananda Aug 15 '18 at 09:21
0

It should be possible to invoke the non-shell-internal version by giving the full path (which you could get with which echo). There are not separate manpages for shell internals; for documentation on those you'll want to look for the manpage for your shell. The "type" command you mention above is the best way to figure out which you'll get.

Pat Gunn
  • 151
  • 1
    My question was how to tell whether the man page is correct. Perhaps the example was misleading; I am speaking more so of two commands that have the same name (different versions of ps or something), and how to tell whether the info I’m getting from the man page is accurate. – extremeaxe5 Aug 05 '18 at 00:32
  • Your phrasing indicates some confusion ; the man page is correct for the independent binaries on your system, but whether you're running the binaries or the shell internal version of these commands depends on what you do and what configuration options you have. The most common source of surprise here is shell-internal versus external binary. That said, it is possible (if unlikely) you might have multiple versions of the same command present on your system. If that's the case, you can see if you have the right manpage by asking your package manager to list all files in the package for a util. – Pat Gunn Aug 12 '18 at 00:54
-1

Since the command you want to get information on is a shell built-in, typing help <command name> in the same shell will give you the correct help entry:

$ help echo
echo: echo [-neE] [arg ...]
    Write arguments to the standard output.
    ...

Alternatively, you can type man bash(or whatever shell you are using) and find the builtin you were looking for.

Unfortunately, there is no easy way to verify that a man page fully matches the command you want to run. Getting the "right" page is trickier than it seems, as that will depend on many factors such as the command's full path, environment variables and aliases, and it's technically impossible for man do account for all such factors. However, after a short while you should develop general understanding of where to look for help.

If I were to describe a general algorithm of getting the right documentation on most modern *nices, it would look something like this:

  • Do you need help with a built-in (type <command> says it's built-in)?
    • Use help <command> or man <shellname> if help is unavailable in your shell.
  • Do you want your help succinct and technical?
    • Use man <command> (or man <section> <command> if there are multiple entries in different sections, see man man for the list of sections)
  • Do you want your help in the form of a lengthier interactive tutorial/manual (if available)?
    • use info <command>
  • If the above steps fail:
    • Check /usr/share/doc/<package name> for additional documentation on the package, such as HTML pages.
    • Run the command with the -h or --help options, assuming the command is to be trusted. That will oftentimes give a brief summary of what it does and tell you where you can find more information.
    • Google.

but I must reiterate, this all will become "natural" as one spends some time with the OS.

undercat
  • 1,857
  • 1
    Only if the current shell happens to be bash. – Kusalananda Aug 05 '18 at 12:07
  • Correct, on a typical UNIX, you get ERROR: Key 'echo' not found (he1) since help is a command from the SCCS suite. – schily Aug 05 '18 at 12:09
  • @Kusalananda based on OP's tag history I highly suspect the shell in question is bash, but fair enough! I would encourage using help if it's available, however, since it is the most straightforward way of getting help with any builtins your shell has. – undercat Aug 05 '18 at 12:19
  • 1
    On OpenBSD, which does not use bash by default, help is a synonym for man, which would give the wrong version of the manual when used as help echo. – Kusalananda Aug 05 '18 at 12:22
-4

man is split in section:

  1. General Section
  2. System Calls
  3. Library Functions
  4. File Formats
  5. Games and screensavers
  6. Miscellaneous
  7. System administration

Depending on what you are looking for you can invoke man like that to avoid confusion: man section command.

For more information you can actually use man man

Claudio Cortese
  • 127
-4

If your OS distro does not have man pages for those programs that mention the differences, you should make bug report.

In fact, this is the task of the distro creators, but if you type:

type cmdname

you will get output whether cmdname is a shell builtin. If you know what shell you are using, you could run:

man shellname

replacing shellname with the name ouf your shell. The man page of your shell should contain information about builtin commands.

Let me give an example on how a user friendly UNIX should document this: http://schillix.sourceforge.net/man/man1/test.1.html

schily
  • 19,173