.ig
	@(#)intro	1.1	11/7/83
	@(#)Copyright (C) 1983 by National Semiconductor Corp.
..
.ds CH "
.ds CF "- \\n(PN -
.af PN i
.pn 7
.TL
INTRODUCTION TO VOLUME 1
.LP
This volume describes the features of the 
\s-2GENIX\s0
system.
It does not attempt to provide perspective or tutorial information on the
\s-2GENIX\s0
operating system, its facilities, or its implementation.
Various documents on those topics are contained in Volume 2.
For an overview of the operating system, see 
.ul
The \s-2UNIX\s0 Time-Sharing System 
by Ritchie and Thompson; for a tutorial, see
.ul
\s-2GENIX\s0 for Beginners.
.LP
This volume attempts to 
describe each program as it is, not as it should be.
Inevitably, this means that various sections will soon be obsolete.
.LP
The volume is divided into eight sections:
.DS
1.      Commands
2.      System calls
3.      Subroutines
4.      Special files
5.      File formats and conventions
6.      Games
7.      Macro packages and language conventions
8.      Maintenance commands and procedures
.DE
Commands are programs intended to be invoked directly by
the user, as opposed to subroutines, which are
intended to be called by the user's programs.
Commands generally reside in directory
.I /bin
(for
.I bin ary 
programs).
Some programs also reside in
.I /\|usr/\|bin ,
.I /\|usr/\|ucb ,
or 
.I /\|usr/\|nsc ,
to save space in
.I /bin .
These directories are searched automatically by the command interpreters.
.LP
System calls are entries into the
\s-2GENIX\s0
supervisor.  The system call interface is identical to a C language
procedure call; the equivalent C procedures are described in Section 2.
.LP
An assortment of subroutines is described in Section 3.
The primary libraries in which they are kept are described in
.I intro (3).
The functions are described in terms of C, but most will
work with other languages as well.
.LP
Section 4, special files, discusses the characteristics of
each system `file' that actually refers to an I/O device.
.LP
The file formats and conventions (Section 5) documents the
structure of particular kinds of files;
for example, the form of the output of the loader and
assembler is given.  Excluded are files used by only one command,
for example the assembler's intermediate files.
.LP
Games are described in Section 6.
.LP
Section 7 contains miscellaneous information needed to
write in various specialized languages: character codes, 
macro packages for typesetting, etc.
.LP
Section 8, maintenance, discusses commands and procedures 
the ordinary user does not need.
The commands and files described here are almost all kept in the directory
.I /etc.
.LP
Each section consists of a number of independent
entries of a page or so each.
The name of the entry is in the upper corners of its pages,
together with the section number, and sometimes a
letter characteristic of a subcategory, e.g. 
the math library is 3M.
Entries within each section are alphabetized.
The page numbers of each entry start at 1;
because the document is 
republished in many variant forms,
consecutive page numbering
is not feasible.
.LP
All entries are based on a common format
(all of these subsections need not always appear).
.RS
.LP
The
.I name
subsection lists the exact names of the commands and subroutines
covered under the entry and gives a very short description of their purpose.
.LP
The
.I synopsis ""
summarizes the use of the program being described.
A few conventions are used, particularly in the Commands subsection:
.LP
.RS
.B Boldface
words are considered literals, and are typed just as they appear.
.LP
Square brackets [ ] around an argument indicate that the argument is optional.
When an argument is given as `name', it always refers to a file name.
.LP
Ellipses `.\|.\|.' are used to show that the previous argument-prototype
may be repeated.
.LP
A final convention is used by the commands themselves.
An argument beginning with a minus sign `\-' is often taken to mean some
sort of option-specifying argument even if it appears in a position where
a file name could appear.  Therefore, it is unwise to have files whose
names begin with `\-'.
.LP
.RE
The
.I description ""
subsection discusses in detail the subject at hand.
.LP
The
.I files ""
subsection gives the names of files which are built into the program.
.LP
A
.I
see also
.R
subsection gives pointers to related information.
.LP
A
.I  diagnostics
subsection discusses the diagnostic indications which may be produced.
Messages which are intended to be self-explanatory are not listed.
.LP
The
.I bugs ""
subsection describes known bugs and sometimes lists deficiencies.
The suggested fix may also be described.
.LP
.RE
The Table of Contents is
organized by section and alphabetically within each section.
A permuted index derived from the Table of Contents is also included.
Within each index entry, the title of the write-up to which
it refers is followed by the appropriate section number in parentheses.
This is important because 
names are duplicated among the sections,
arising principally from commands which
exist only to exercise a particular system call.
.SH
HOW TO GET STARTED
.LP
This section sketches the basic information you need to get started on
the \s-2GENIX\s0 operating system,
how to log in and log out, how to communicate through your terminal,
and how to run a program.
See `\c
\s-2GENIX\s0
for Beginners' in Volume 2 for a more complete introduction to the system.
.LP
.I
Logging in.\ \ 
.R
You must log into 
\s-2GENIX\s0
from an appropriate terminal, such as a VT100-compatible terminal.  
You must also have a valid user name.  
.LP
For all terminals, 
type your name in lower-case if possible; if you type
upper-case letters,
\s-2GENIX\s0
will assume that your terminal cannot generate lower-case
letters and will translate all subsequent upper-case letters to lower case.
.LP
When you have successfully logged, the shell program
types a prompt (`$' or `%') to you.
(The shells are described under `How to run a program.')
.LP
For more information, consult
.I tset (1),
and
.I stty (1),
which tell how to adjust terminal behavior,
.I getty (8),
which discusses the login sequence in more detail, and
.I tty (4),
which discusses terminal I/O.
.LP
.I
Logging out.\ \ 
.R
There are three ways to log out:
.IP
By typing an end-of-file indication (EOT character, control-d) to the shell.
The shell will terminate and the `login: ' message will appear again.
.IP
By typing ``logout.''
.IP
You can log in directly as another user by giving a
.I login (1)
command.
This logs out the old user.
.LP
.I
How to communicate through your terminal.\ \ 
.R
When you type characters at your terminal, the characters are placed
in an input buffer and are not
given to a program until you type a return (or newline).   
.R
.LP
\s-2GENIX\s0
terminal I/O is full-duplex.
It has full read-ahead, which means that you can type at any time,
even while a program is outputting data on your terminal.
Of course, if you type during output, the printed output will
have the input characters interspersed.
However, whatever you type will be saved up and interpreted in
the correct sequence.
The amount of read-ahead is limited, 
but it is generous and not likely to be exceeded.
When the read-ahead limit is exceeded, the system
throws away all the saved characters (or beeps, if your prompt was a %).
.LP
A backspace (control-h) erases the previous character on a command
line.
Control-u erases the entire line.  
Successive uses of backspace erase characters back to, but
not beyond, the beginning of the line.
' and `#' can be transmitted to a program by preceding them with `\\'.
.LP
The `break' or `interrupt' key causes an
.I
interrupt signal,
.R
as does the \s8ASCII\s10 `delete' (or `rubout') character,
which is not passed to programs.
This signal generally causes whatever program you are running to terminate.
It is typically used to stop a long printout that you don't want.
However, programs can arrange either to ignore this signal altogether,
or to be notified when it happens, instead of being terminated.
The editor, for example, catches interrupts and stops what it is doing,
instead of terminating, so that an interrupt can
be used to halt an editor printout without losing the file being edited.
Many users change this interrupt character to be ^C (control-C) using
\fIstty\fR(1).
.LP
It is also possible to suspend output temporarily using ^S (control-s)
and later resume output with ^Q (control-q).
In a newer terminal driver, it is possible to cause output to be thrown
away without interrupting the program by typing ^O (control-o); see
.I newtty (4).
.LP
The
.I quit ""
signal is generated by typing the \s8ASCII\s10 FS character.
(FS appears many places on different terminals, most commonly
as control-\e or control-\^|\^.)
It not only causes a running program to terminate,
but also generates a file with the core image of the terminated process.
.I Quit 
is useful for debugging.
.LP
Besides adapting to the speed of the terminal,
\s-2GENIX\s0
tries to be intelligent about whether
you have a terminal with the newline function,
or whether it must be simulated with carriage-return and line-feed.
In the latter case, all input carriage returns
are converted to newline characters, the standard line delimiter,
and both a carriage return and a line feed are echoed to the terminal.
If you get into the wrong mode, the
.I reset (1)
command will rescue you.
.LP
Tab characters are used freely in
\s-2GENIX\s0
source programs.
If your terminal does not have the tab function,
you can arrange to have them turned into spaces
during output, and echoed as spaces during input.
The system assumes that tabs are set every eight columns.
Again, the
.I tset (1)
or
.I stty (1)
command will set or reset this mode.
.I Tset (1)
can be used to set the tab stops automatically when necessary.
.LP
.I
How to run a program; the shells.\ \ 
.R
When you have successfully logged in, a program
called the shell is waiting for you to enter commands.
The command name is always the first word on an input line;
it and its arguments are separated from one another by spaces.
The shell reads typed-in lines, splits them up
into a command name and arguments, and executes the command.
A command is simply an executable program.
The shell looks in several system directories to find the command.  You can also
place commands in your own directory and have the shell find them there.
There is nothing special about system-provided
commands except that they are kept in a directory where the shell
can find them.
.LP
When a program terminates, the shell will ordinarily regain control and type 
a prompt to indicate that it is ready for another command.
.LP
The shells have many other capabilities, which are described in detail in
.I sh (1)
and
.I csh (1).
The default prompt symbol identifies the shell that is running:  
`$' indicates the Bourne shell, 
.I sh ,
and 
`%' indicates the C shell,
.I csh .
The shells are different for all but the most simple terminal usage.
Most users choose
.I csh (1)
because of the
.I history
mechanism and the
.I alias
feature, which greatly enhance its power when used interactively.
The C shell
also supports the job-control facilities.    
See
.I csh (1)
or the introduction to the C Shell in volume 2 for details.
.LP
You can change from one shell to the other by using the
.I chsh (1)
command, which takes effect at your next login.
.LP
.I
The current directory.\ \ 
.R
The \s-2GENIX\s0
file system is arranged in a hierarchy of directories.
When the system administrator gave you a user name,
you were also given a directory, ordinarily
with the same name as your user name.
When you log in, any file you create is by default in this directory.
Because you are the owner of this directory, you have
full permission to read, write, alter, or destroy its contents.
Permissions in other directories
and files will have been granted or denied to you by their owners.
As a matter of observed fact, few
\s-2GENIX\s0
users protect their files from others.
.LP
To change the current directory (but not the set of permissions you
were endowed with at login) use
.I cd (1).
.LP
.I
Path names.\ \ 
.R
To refer to files not in the current directory, you must use a path name.
Full path names begin with `/', the name of the root directory of the
whole file system.
After the slash comes the name of each directory containing the next
sub-directory (followed by a `/') until finally the file name is reached.
For example,
.I
/\^u/\^lem/\^filex
.R
refers to the file
.I
filex
.R
in the directory
.I
lem; lem
.R
is itself a subdirectory of
.I
u; u
.R
springs directly from the root directory.
.LP
If your current directory has subdirectories,
the path names of files begin with
the name of the subdirectory with no prefixed `/'.
.LP
A path name may be used anywhere a file name is required.
.LP
Important commands which modify the contents of directories and files are
.I cp (1),
.I mv (1),
and
.I rm (1),
which respectively copy, move (i.e. rename) and remove files.
To find out the status of files or directories, use 
.I ls (1).
See
.I mkdir (1)
for making directories and
.I
rmdir
.R
in
.I rm (1)
for removing them.
.LP
For a more complete discussion of the file system, see
`The
\s-2UNIX\s0
Time-Sharing System,'
by Ken Thompson and Dennis Ritchie.
A review of Section 2 of this manual, which
discusses system calls, may be useful even if you do not intend
to deal with the system at that level.
.LP
.I
Writing a program.\ \ 
.R
To enter the text of a source program into a
\s-2GENIX\s0
file, use the editor
.I ex (1)
or its display editing version
.I vi (1).
The old line
.I ed (1)
is also available.
The principal languages supported by the 
\s-2GENIX\s0 operating system
are C and, optionally, Pascal.
The C compiler is
.I cc (1),
and 
the Pascal compiler is 
.I pc (1).
Pass the file containing the source program
to the appropriate language processor as an argument.
The output of the language processor
is left on a file in the current directory named `a.out'.
(If the output is valuable, use
.I mv
to move it to a less exposed name soon.)\ 
.LP
When you have gone through this entire process
without provoking any diagnostics, the resulting program
can be run by giving its name to the shell
in response to the shell (`$' or `%') prompt.
.LP
Your programs can receive arguments from the command line
just as system programs do;
see
.I exec (2).
.LP
.I
Text processing.\ \ 
.R
Almost all text is entered through 
.I ex (1)
and
.I vi (1)
editors.
The commands most often used to write text on a terminal are:
.I
cat, pr, more
.R
and
.I nroff,
all in Section 1.
.LP
The
.I cat
command simply dumps \s8ASCII\s10 text
on the terminal, with no processing at all.
The
.I pr ""
command paginates the text, supplies headings,
and has a facility for multi-column output.
.I
Nroff
.R
is an elaborate text formatting program.
.I Troff
prepares documents for a phototypesetter or a laser printer;
it is very similar to 
.I nroff,
and often works from exactly the same source text.
The macro packages 
.I me (7)
and
.I ms (7)
are supplied to make text processing easier.
.LP
.I More (1)
is useful for preventing the output of a command from
scrolling off the top of your screen.
It is also well suited to examining files.
.LP
.I
Status inquiries.\ \ 
.R
Various commands exist to provide you with useful information.
The
.I w (1)
command
prints a list of users presently logged in, and what they are doing.
The
.I date (1)
command
prints the current time and date.
The
.I ls (1)
command
lists the files in your directory or give
summary information about particular files.
.LP
.I
Surprises.\ \ 
.R
Certain commands provide inter-user communication.
Even if you do not plan to use them, it would be
well to learn something about them, because someone else may aim them at you.
.LP
To communicate with another user currently logged in,
.I write (1)
is used;
.I mail (1)
leaves messages, which are announced
to other users when they next log in.
The write-ups in the manual also suggest how to respond to
the two commands if you are a target.
.LP
If you use
.I csh (1)
the key ^Z (control-Z) will cause jobs to ``stop.''
If this happens before you learn about it,
you can simply continue by saying ``fg'' (for foreground) to bring
the job back.
.LP
When you log in, a message-of-the-day may greet you before the first prompt.
