freebsd-src/share/doc/handbook/basics.sgml

<!-- $Id$ -->
<!-- The FreeBSD Documentation Project -->

<chapt><heading>Unix Basics<label id="basics"></heading>

      <sect>
	<heading>The online manual<label id="basics:man"></heading>

	<p>The most comprehensive documentation on FreeBSD is in
	  the form of <em>man pages</em>.  Nearly every program
	  on the system comes with a short reference manual
	  explaining the basic operation and various arguments.
	  These manuals can be view with the
	  <tt><bf>man</bf></tt> command.  Use of the
	  <tt><bf>man</bf></tt> command is simple:
	  <tscreen>
	    <bf>man</bf> <it>command</it>
	  </tscreen>
	  where <it>command</it> is the name of the command
	  you wish to learn about.  For example, to learn more about
	  <tt><bf>ls</bf></tt> command type:
	  <tscreen>
	    % <bf>man ls</bf>
	  </tscreen>

	<p>The online manual is divided up into numbered
	  sections:
	  <enum>
	    <item>User commands</item>
	    <item>System calls and error numbers</item>
	    <item>Functions in the C libraries</item>
	    <item>Device drivers</item>
	    <item>File formats</item>
	    <item>Games and other diversions</item>
	    <item>Miscellaneous information</item>
	    <item>System maintenance and operation commands</item>
	  </enum>
	  in some cases, the same topic may appear in more than
	  one section of the on-line manual.  For example, there
	  is a <tt><bf>chmod</bf></tt> user command and a
	  <tt><bf>chmod()</bf></tt> system call.  In this case,
	  you can tell the <tt><bf>man</bf></tt> command which
	  one you want by specifying the section:
	  <tscreen>
	    % <bf>man 1 chmod</bf>
	  </tscreen>
	  which will display the manual page for the user command
	  <tt><bf>chmod</bf></tt>.  References to a particular
	  section of the on-line manual are traditionally placed
	  in parenthesis in written documentation, so
	  <tt><bf>chmod(1)</bf></tt> refers to the <tt><bf>chmod
	  </bf></tt> user command and <tt><bf>chmod(2)</bf></tt>
	  refers to the system call.

	<p>This is fine if you know the name of the command and
	  simply wish to know how to use it, but what if you cannot recall the
	  command name?  You can use <tt><bf>man</bf></tt> to
	  search for keywords in the command <em>descriptions</em> by
	  using the <tt><bf>-k</bf></tt> switch:
	  <tscreen>
	    % <bf>man -k mail</bf>
	  </tscreen>
	  With this command you will be presented with a list of
	  commands that have the keyword `mail' in their
	  descriptions.  This is actually functionally equivalent to
	  using the <tt><bf>apropos</bf></tt> command.

	<p>So, you are looking at all those fancy commands in <tt>
	  /usr/bin</tt> but do not even have the faintest idea
	  what most of them actually do?  Simply do a
	  <tscreen>
	    % <bf>cd /usr/bin; man -f *</bf>
	  </tscreen>
	  or
	  <tscreen>
	    % <bf>cd /usr/bin; whatis *</bf>
	  </tscreen>
	  which does the same thing.

      <sect>
	<heading>GNU Info files<label id="basics:info"></heading>

	<p>FreeBSD includes many applications and utilities
	  produced by the Free Software Foundation (FSF).  In
	  addition to man pages, these programs come with more
	  extensive hypertext documents called <em>info</em>
	  files which can be viewed with the <tt>info</tt>
	  command or, if you installed <tt>emacs</tt>, the info
	  mode of <tt>emacs</tt>.
	      
          To use the <tt>info(1)</tt> command, simply type:
          <tscreen>% <bf>info</bf></tscreen>  For a brief
          introduction, type <tt><bf>h</bf></tt>.  For a quick
          command reference, type <tt><bf>?</bf></tt>.