Linux man vs info vs help confusion

genogebot · 11-25-2015, 12:29 AM

I'm using Linux Mint XFCE, and I wanted to find some information about the bash shell command 'read' so I opened up a terminal and typed 'man read' - but I got a page about the C programming function read().

Then I tried 'info read' but that gave me a page about the 'readlink' command.

Finally I tried 'help read' and that gave me what I wanted.

I know from past experience that there are man pages for other shell commands, so what's with 'read'? Is it just that nobody has ever written a man page for the shell command 'read', or is it that somebody got in first with 'read()' so 'read' couldn't be added?

Is there a better way of finding information than just jumping from man to info to help in the hope of finding what I want? Sometimes this combination of man/info/help seems chaotically messy, and I can't help wondering if I'm not searching correctly.

chrism01 · 11-25-2015, 02:15 AM

There are multiple sections to the man pages - read this for background https://en.wikipedia.org/wiki/Man_page#Manual_sections.
(you'll see that the same keyword can appear in different sections with different definitions - its all about context)

See also http://man7.org/linux/man-pages/dir_all_by_section.html and for searching I use http://linux.die.net/man/.

HTH

genogebot · 11-25-2015, 02:35 AM

Quote:

Originally Posted by chrism01

There are multiple sections to the man pages - read this for background https://en.wikipedia.org/wiki/Man_page#Manual_sections.
(you'll see that the same keyword can appear in different sections with different definitions - its all about context)

See also http://man7.org/linux/man-pages/dir_all_by_section.html and for searching I use http://linux.die.net/man/.

HTH

Thanks for that. That clears up some things that have puzzled me for a while. And I've bookmarked the links.

In the case of 'read', it seems that I should be able to find it in section 1, along with other bash commands, by typing 'man 1 read' but as I get the response 'No manual entry for read in section 1' I assume nobody has ever written a man page for read, or at least included it in the Ubuntu version of the man pages.

berndbausch · 11-25-2015, 02:49 AM

Quote:

Originally Posted by genogebot

Thanks for that. That clears up some things that have puzzled me for a while. And I've bookmarked the links.

In the case of 'read', it seems that I should be able to find it in section 1, along with other bash commands, by typing 'man 1 read' but as I get the response 'No manual entry for read in section 1' I assume nobody has ever written a man page for read, or at least included it in the Ubuntu version of the man pages.

read is not a command in the sense of cp, cat, ls and so on. It's built into the shell and doesn't have its own man page for that reason. To the no-so-technical user, the distinction is probably not clear, and it's rather natural that you want to find it in man section 1, but such is life.

Try info bash or man bash, or the bash reference manual.

zhjim · 11-25-2015, 02:54 AM

As read is a builtin command of bash it does not have an own man pages. But more over its within the man bash page. So is the builtin command help. Which on the opposite of man only 'helps' on builtin commands of bash. Also you state that you found the read command in section 1 of man I doubt that it is really the read builtin command man page due to it beeing builtin...

If that does not make much of a sense lets say it in bash:

Quote:

kobold@rm:~$ whatis man
man (1) - an interface to the on-line reference manuals
man (7) - macros to format man pages
kobold@rm:~$ whatis info
info (1) - read Info documents
info (5) - readable online documentation
kobold@rm:~$ whatis help
help: nothing appropriate.
kobold@rm:~$ help man
-bash: help: no help topics match `man'. Try `help help' or `man -k man' or `info man'.
kobold@rm:~$ help info
-bash: help: no help topics match `info'. Try `help help' or `man -k info' or `info info'.
kobold@rm:~$ help help
help: help [-dms] [pattern ...]
Display information about builtin commands.

Displays brief summaries of builtin commands. If PATTERN is
specified, gives detailed help on all commands matching PATTERN,
otherwise the list of help topics is printed.

Options:
-d output short description for each topic
-m display usage in pseudo-manpage format
-s output only a short usage synopsis for each topic matching
PATTERN

Arguments:
PATTERN Pattern specifiying a help topic

Exit Status:
Returns success unless PATTERN is not found or an invalid option is given.

genogebot · 11-25-2015, 04:45 AM

Quote:

Originally Posted by berndbausch

read is not a command in the sense of cp, cat, ls and so on.

Ok, I didn't know that. I assumed it was just another command like mkdir, etc.

Quote:

Originally Posted by zhjim

Also you state that you found the read command in section 1 of man

No, I said I didn't find it - I got the response 'No manual entry for read in section 1' when I tried.

It does make it difficult when the linux command information is scattered across different help systems. I'm starting to think I'd be better off going straight to google instead of trying to find information on my computer - at least it's a unified search system.

berndbausch · 11-25-2015, 05:02 AM

Quote:

Originally Posted by genogebot

I'm starting to think I'd be better off going straight to google instead of trying to find information on my computer - at least it's a unified search system.

Good luck finding help for read though

DavidMcCann · 11-25-2015, 11:44 AM

I tend to use the on-line sources mentioned by Chris, but a useful command is "apropos". Using "apropos read" gives a ton of answers which includes
read [builtins] (1) - bash built-in commands, see bash(1)

genogebot · 11-25-2015, 01:00 PM

Quote:

Originally Posted by berndbausch

Good luck finding help for read though

Searching with StartPage : second hit is 'read man page - LinuxCommand.org'

Quote:

Originally Posted by DavidMcCann

I tend to use the on-line sources mentioned by Chris, but a useful command is "apropos". Using "apropos read" gives a ton of answers which includes
read [builtins] (1) - bash built-in commands, see bash(1)

Hmm

... on my system I also get a lot of answers from 'apropos read' but none of them refer to 'read [builtins]':

Code:

apropos read
FBReader (1)         - e-book reader
__freadable (3)      - interfaces to stdio FILE structure
__freading (3)       - interfaces to stdio FILE structure
_llseek (2)          - reposition read/write file offset
_sysctl (2)          - read/write system parameters
accessdb (8)         - dumps the content of a man-db database in a human readable format
aio_read (3)         - asynchronous read
amidi (1)            - read from and write to ALSA RawMIDI ports
arch_prctl (2)       - set architecture-specific thread state
Archive::Zip::MemberRead (3pm) - A wrapper that lets you read Zip archive members as if they were files.
capget (2)           - set/get capabilities of thread(s)
capset (2)           - set/get capabilities of thread(s)
cdparanoia (1)       - an audio CD reading utility which includes extra data verification features
cdrdao (1)           - reads and writes CDs in disc-at-once mode
dpkg-reconfigure (8) - reconfigure an already installed package
endaliasent (3)      - read an alias entry
eventfd_read (3)     - create a file descriptor for event notification
exit_group (2)       - exit all threads in a process
fbreader (1)         - e-book reader
fc-cat (1)           - read font information cache files
fgetwc (3)           - read a wide character from a FILE stream
fgetws (3)           - read a wide-character string from a FILE stream
fread (3)            - binary stream input/output
fread_unlocked (3)   - nonlocking stdio functions
fts_read (3)         - traverse a file hierarchy
get_thread_area (2)  - get a thread-local storage (TLS) area
getaliasbyname (3)   - read an alias entry
getaliasbyname_r (3) - read an alias entry
getaliasent (3)      - read an alias entry
getaliasent_r (3)    - read an alias entry
getcpu (2)           - determine CPU and NUMA node on which the calling thread is running
gettid (2)           - get thread identification
getwc (3)            - read a wide character from a FILE stream
getwchar (3)         - read a wide character from standard input
gipddecode (1)       - Decode a GIPD stream into human readable form.
git-prune-packed (1) - Remove extra objects that are already in pack files
git-read-tree (1)    - Reads tree information into the index
git-symbolic-ref (1) - Read, modify and delete symbolic refs
hbpldecode (1)       - Decode a HBPL stream into human readable form.
hipercdecode (1)     - Decode a HIPERC stream into human readable form.
info (1)             - read Info documents
info (5)             - readable online documentation
infobrowser (1)      - read Info documents
intel_bios_reader (1) - Parses an Intel BIOS and displays many of its tables
intel_reg_read (1)   - Reads an Intel GPU register value
io_getevents (2)     - read asynchronous I/O events from the completion queue
javac (1)            - Reads Java class and interface definitions and compiles them into bytecode and class files.
jpegexiforient (1)   - reads or writes the Exif Orientation Tag
jstack (1)           - Prints Java thread stack traces for a Java process, core file, or remote debug server. This command is experimental and unsupported.
klogctl (3)          - read and/or clear kernel message ring buffer; set console_loglevel
lavadecode (1)       - Decode a LAVAFLOW stream into human readable form.
line (1)             - read one line
llseek (2)           - reposition read/write file offset
lowntfs-3g (8)       - Third Generation Read/Write NTFS Driver
lseek (2)            - reposition read/write file offset
lseek64 (3)          - reposition 64-bit read/write file offset
mount.lowntfs-3g (8) - Third Generation Read/Write NTFS Driver
mount.ntfs (8)       - Third Generation Read/Write NTFS Driver
mount.ntfs-3g (8)    - Third Generation Read/Write NTFS Driver
Net::DBus::Binding::Iterator (3pm) - Reading and writing message parameters
ntfs-3g (8)          - Third Generation Read/Write NTFS Driver
ntptime (8)          - read kernel time variables
numfmt (1)           - Convert numbers from/to human-readable strings
oakdecode (1)        - Decode an OAKT printer stream into human readable form.
opldecode (1)        - Decode a Raster Object (opl) stream into human readable form.
pbmreduce (1)        - read a portable bitmap and reduce it N times
pciconfig_read (2)   - pci device information handling
pnmenlarge (1)       - read a portable anymap and enlarge it N times
ppmspread (1)        - displace a portable pixmap's pixels by a random amount
pread (2)            - read from or write to a file descriptor at a given offset
pread64 (2)          - read from or write to a file descriptor at a given offset
preadv (2)           - read or write data into multiple buffers
process_vm_readv (2) - transfer data between process address spaces
pthread_attr_destroy (3) - initialize and destroy thread attributes object
pthread_attr_getaffinity_np (3) - set/get CPU affinity attribute in thread attributes object
pthread_attr_getdetachstate (3) - set/get detach state attribute in thread attributes object
pthread_attr_getguardsize (3) - set/get guard size attribute in thread attributes object
pthread_attr_getinheritsched (3) - set/get inherit-scheduler attribute in thread attributes object
pthread_attr_getschedparam (3) - set/get scheduling parameter attributes in thread attributes object
pthread_attr_getschedpolicy (3) - set/get scheduling policy attribute in thread attributes object
pthread_attr_getscope (3) - set/get contention scope attribute in thread attributes object
pthread_attr_getstack (3) - set/get stack attributes in thread attributes object
pthread_attr_getstackaddr (3) - set/get stack address attribute in thread attributes object
pthread_attr_getstacksize (3) - set/get stack size attribute in thread attributes object
pthread_attr_init (3) - initialize and destroy thread attributes object
pthread_attr_setaffinity_np (3) - set/get CPU affinity attribute in thread attributes object
pthread_attr_setdetachstate (3) - set/get detach state attribute in thread attributes object
pthread_attr_setguardsize (3) - set/get guard size attribute in thread attributes object
pthread_attr_setinheritsched (3) - set/get inherit-scheduler attribute in thread attributes object
pthread_attr_setschedparam (3) - set/get scheduling parameter attributes in thread attributes object
pthread_attr_setschedpolicy (3) - set/get scheduling policy attribute in thread attributes object
pthread_attr_setscope (3) - set/get contention scope attribute in thread attributes object
pthread_attr_setstack (3) - set/get stack attributes in thread attributes object
pthread_attr_setstackaddr (3) - set/get stack address attribute in thread attributes object
pthread_attr_setstacksize (3) - set/get stack size attribute in thread attributes object
pthread_cancel (3)   - send a cancellation request to a thread
pthread_cleanup_pop (3) - push and pop thread cancellation clean-up handlers
pthread_cleanup_pop_restore_np (3) - push and pop thread cancellation clean-up handlers while saving cancelability type
pthread_cleanup_push (3) - push and pop thread cancellation clean-up handlers
pthread_cleanup_push_defer_np (3) - push and pop thread cancellation clean-up handlers while saving cancelability type
pthread_create (3)   - create a new thread
pthread_detach (3)   - detach a thread
pthread_equal (3)    - compare thread IDs
pthread_exit (3)     - terminate calling thread
pthread_getaffinity_np (3) - set/get CPU affinity of a thread
pthread_getattr_np (3) - get attributes of created thread
pthread_getconcurrency (3) - set/get the concurrency level
pthread_getcpuclockid (3) - retrieve ID of a thread's CPU time clock
pthread_getname_np (3) - set/get the name of a thread
pthread_getschedparam (3) - set/get scheduling policy and parameters of a thread
pthread_join (3)     - join with a terminated thread
pthread_kill (3)     - send a signal to a thread
pthread_kill_other_threads_np (3) - terminate all other threads in process
pthread_self (3)     - obtain ID of the calling thread
pthread_setaffinity_np (3) - set/get CPU affinity of a thread
pthread_setcancelstate (3) - set cancelability state and type
pthread_setcanceltype (3) - set cancelability state and type
pthread_setconcurrency (3) - set/get the concurrency level
pthread_setname_np (3) - set/get the name of a thread
pthread_setschedparam (3) - set/get scheduling policy and parameters of a thread
pthread_setschedprio (3) - set scheduling priority of a thread
pthread_sigmask (3)  - examine and change mask of blocked signals
pthread_sigqueue (3) - queue a signal and data to a thread
pthread_testcancel (3) - request delivery of any pending cancellation request
pthread_timedjoin_np (3) - try to join with a terminated thread
pthread_tryjoin_np (3) - try to join with a terminated thread
pthread_yield (3)    - yield the processor
pthreads (7)         - POSIX threads
pwrite (2)           - read from or write to a file descriptor at a given offset
pwrite64 (2)         - read from or write to a file descriptor at a given offset
pwritev (2)          - read or write data into multiple buffers
qpdldecode (1)       - Decode a QPDL stream into human readable form.
read (2)             - read from a file descriptor
readahead (2)        - perform file readahead into page cache
readcd (1)           - read or write data Compact Discs or related madia
readdir (2)          - read directory entry
readdir (3)          - read a directory
readdir_r (3)        - read a directory
readelf (1)          - Displays information about ELF files.
readline (3readline) - get a line from a user with editing
readlink (1)         - print resolved symbolic links or canonical file names
readlink (2)         - read value of a symbolic link
readlinkat (2)       - read value of a symbolic link relative to a directory file descriptor
readprofile (1)      - read kernel profiling information
readv (2)            - read or write data into multiple buffers
sched_getaffinity (2) - set and get a thread's CPU affinity mask
sched_getcpu (3)     - determine CPU on which the calling thread is running
sched_setaffinity (2) - set and get a thread's CPU affinity mask
seekdir (3)          - set the position of the next readdir() call in the directory stream.
set_thread_area (2)  - set a thread local storage (TLS) area
set_tid_address (2)  - set pointer to thread ID
setaliasent (3)      - read an alias entry
setns (2)            - reassociate thread with a namespace
slxdecode (1)        - Decode a SLX stream into human readable form.
sprof (1)            - Read and display shared object profiling data
sysctl (2)           - read/write system parameters
syslog (2)           - read and/or clear kernel message ring buffer; set console_loglevel
syslog (3)           - read and/or clear kernel message ring buffer; set console_loglevel
tee (1)              - read from standard input and write to standard output and files
Term::UI (3pm)       - Term::ReadLine UI made easy
tgkill (2)           - send a signal to a thread
tkill (2)            - send a signal to a thread
ureadahead (8)       - Read files in advance during boot
writev (2)           - read or write data into multiple buffers
wsgen (1)            - Reads a web service endpoint implementation (SEI) class and generates all of the required artifacts for web service deployment, and...
x86_64-linux-gnu-readelf (1) - Displays information about ELF files.
xqxdecode (1)        - Decode a XQX stream into human readable form.
YAML::Tiny (3pm)     - Read/Write YAML files with as little code as possible
zjsdecode (1)        - Decode a ZjStream into human readable form.

Habitual · 11-25-2015, 01:16 PM

genogebot:

for external commands that may have a man page, use
which <term>
If found then man <term> or other info/apropos...

If not found by which <term>, use
type <term>

eg:

Code:

which read
$ 
$ type read
read is a shell builtin

Just a tip from the cheap seats.

Have a Great Day!

genogebot · 11-25-2015, 01:55 PM

Quote:

Originally Posted by Habitual

genogebot:

for external commands that may have a man page, use
which <term>
If found then man <term> or other info/apropos...

If not found by which <term>, use
type <term>

eg:

Code:

which read
$ 
$ type read
read is a shell builtin

Just a tip from the cheap seats.

Have a Great Day!

Thanks, that's useful information. (So many commands, so little time...

)

Keith Hedger · 11-25-2015, 02:30 PM

What I do in order

Code:

unkowncommand -h
unkowncommand -?
unkowncommand --help
man unkowncommand
apropos unkowncommand

Finally google.

astrogeek · 11-25-2015, 02:42 PM

In case you have not thought to look at man man, it is really worthwhile reading for a top down orientation - and not actually very long.

On the other hand, man bash is very long, but very much worth becomming familiar with!

Code:

       read  [-ers]  [-a  aname]  [-d delim] [-i text] [-n nchars] [-N nchars] [-p prompt] [-t timeout] [-u fd]
       [name ...]
              One line is read from the standard input, or from the file descriptor fd supplied as an  argument
              to the -u option, and the first word is assigned to the first name, the second word to the second
              name, and so on, with leftover words and their intervening separators assigned to the last  name.
              If  there are fewer words read from the input stream than names, the remaining names are assigned
              empty values.  The characters in IFS are used to split the line into words.  The backslash  char
              acter (\) may be used to remove any special meaning for the next character read and for line con
              tinuation.  Options, if supplied, have the following meanings:

I recall man page frustrations from my early encounters, but now I generally use them with confidence instead of trepidation. I think much of that confidence comes from realizing that they are mostly complete (i.e. the answer I need actually is in there), and from my own browsing and searching habits learned along the way.

For example, when looking for the above read information, I successively did the following without thinking about it...

Code:

man bash

/read - which searches for and hilights all occurrences of read...
/ - next occurrence...
/

[down arrow] - to scroll past the many read uses in the READLINE section more quickly...

/
/
/ ... AH! there it is!

And if I hit end of page without an answer always look over the SEE ALSO list - that is a 
gold mine of cross-related topics.

So in short, learn the structure of the manual and the pages, and think of it as a comprehensive user manual - that is what it is! Refine your habits of using the pages beyond just the shell options and quick answers, you'll be glad you did!

The bash man page itself is a trove of dense, useful information once you learn your way around. But not much good for late night recreational reading!

Another comment, I always use the man pages first, and do not often need to go further. But, when man does not produce the desired answer, info almost always does. Info tends to have many more details, but usually require more effort on my part to locate what I need. This may be a failing of my methods more so than the info pages themselves.

We have come to expect instant access to information we seek, without actual effort on our part. But it seems to me we often spend much more time looking for "quick" answers than it would take to extract and understand the more useful and complete answer, including its place in the greater context. Man pages require the latter approach to be really useful, but reward your efforts proportionally!

rknichols · 11-25-2015, 02:54 PM

Quote:

Originally Posted by zhjim

As read is a builtin command of bash it does not have an own man pages. But more over its within the man bash page. So is the builtin command help. Which on the opposite of man only 'helps' on builtin commands of bash. Also you state that you found the read command in section 1 of man I doubt that it is really the read builtin command man page due to it beeing builtin...

In many distros (apparently not "Mint") there are indeed manpages for each of the bash builtins, and those all just source the "builtins.1" page, which describes all of them.

genogebot · 11-25-2015, 08:12 PM

Ok, I think this is a good discussion. I've learned a lot from this, I have a much better understanding of the man/info/help systems and my own preference is starting to take shape.

This is my personal take on the Linux man/info/help/etc situation so far, based on my attempts to use them in Linux Mint 17.1 XFCE:

man

Pros: Lots of detailed information

Cons: Finding the required information may require prior knowledge of where to look for it within the man sections. The presence or absence of a particular man page may depend on the distro. Even knowing where to look, and following the steps above as outlined by 'astrogeek', it took me a couple of minutes to hunt through the very lengthy 'bash' page and find the details for the 'read' command. Any problems in using a Linux command may still require an internet search to find solutions.

My summary: Great for experienced Linux users who already have a good idea of where to look, not so good for the less experienced who are hunting around for new information.

info

Pros: Similar to man. Produced better 'apropos' results than man for 'apropos read'. ('man --apropos read' did not list the bash builtins answer, but 'info --apropos read' did.)

Cons: Similar to man. Presumably also distro-dependent, although I haven't had a chance to test that.

My summary: About the same as man, perhaps slightly easier for inexperienced users to find pages.

help

Pros: Good for searching for information on builtin commands that may be harder to find with man or info, as the answer takes you straight to the relevant page.

Cons: It is only for builtin commands.

My summary: Good if you already know that the information you want refers to a builtin command, so again better for experienced Linux users.

--help, -h, -?, etc.

Pros: Good for a quick reminder of command usage.

Cons: These options might work, they might not. Presumably it's up to the whim of the developer.

My summary: Useful if it works.

Internet search

Pros: If the search terms are appropriate, a link to the relevant information may be available almost instantly. (My internet search for 'linux read' gave me the information I wanted as the second link on the results page - the first being the read() command in C - in a couple of seconds.) No need for prior knowledge of specific categories within the Linux man/info/help pages. No need to learn man/info search techniques. Most people already know how to do an internet search. No dependence on distro inclusions/exclusions. Links may also provide information about problems and solutions relating to the use of a command, which is entirely absent from the Linux man pages.

Cons: Poor search terms or searching for obscure information may mean that relevant answers are a long way down among a flood of irrelevant links. Answers may not be relevant for the user's current system.

My summary: Based purely on my own experience, I have to say I think internet searching *usually* provides accurate information much quicker than I can find it using man/info/help, especially when I'm trying to find information about something that is new to me. I don't have to learn any new search methodology, or search in different databases depending on the command category.

My conclusion (so far...):

I use Linux every day on four different computers (one desktop, two laptops and a server, plus a couple of other computers that get intermittent use) and I think it's great. Having said that, I'm not a hardcore Linuxer, I just use it to get things done and I have no desire to learn Linux just for the sake of learning Linux. For me, then, the best solution is the one that gives me the relevant information as quickly and easily as possible, whether it's something I'm already familiar with or not. The man/info/help systems on Linux seem to be designed more as references for the experienced, rather than as learning tools for the inexperienced, so in that sense I think they rate poorly in terms of user-friendliness. Sometimes I've spent way too much time trying to find local information about commands that I've never used before and I won't use again for months or longer, by which time I'll need to look them up again. Based on the discussion on this thread and my own investigation of people's suggestions (and yes, I've tried them all), I think the best first solution for me is internet searching, unless I already have a good idea of where to find the information in the system, in which case I'm happy to use man or info or help or --help or -h or -?.