



   ************************************************************************
   ************************************************************************
   ************************************************************************



                    X    X    X    X     X    X    X
                    X    X    XX   X     X     X  X
                    X    X    X X  X     X      XX
                    X    X    X  X X     X      XX
                    X    X    X   XX     X     X  X
                     XXXX     X    X     X    X    X

                       XXXXXXX  X     X   XXXXX
                          X     X     X  X
                          X     X     X  X   XXX
                          X     X     X  X     X
                          X      XXXXX    XXXXX


                     (UNIX TERMINAL USER'S GUIDE)


               This textbook was written specifically for the
               UNIX  systems  operated  by  the Department of
               Defense,  and  may   contain   references   to
               features available only on those systems.

   ***********************************************************************
   ***********************************************************************
   ***********************************************************************
















                                                        Thomas Leary
                                                         March, 1980













                                  TUG
















                             Acknowledgment

             The "UNIX  TUG"  is  based  upon  the  "Harvard-
             Radcliffe  Student  Timesharing  System Terminal
             User's Guide"(HRSTS-TUG). Permission to use  the
             HRSTS-Tug  was graciously granted by Lew Law and
             Tucker  Taft  of  the  Harvard  Science  Center.
             Inquiries  concerning  the  HRSTS-TUG  should be
             directed to the Director of Technical Services -
             Harvard Science Center, Cambridge, Mass.




































                                  TUG

   0.  Scope of this Manual


   The information presented in this manual is intended as an intro-
   duction  to  UNIX  as  well as a beginners reference guide to the
   commonly used portions of the system.  The vast majority  of  the
   topics  covered are of a basic nature. Where more advanced topics
   are introduced they are identified by an asterisk  following  the
   section  title.   This  manual is not intended as a bible for the
   system, but should guide the  average  user  through  getting  an
   account,  getting "onto" the system, using available programs and
   languages,  getting  "off"  the  system,  and  interpreting   and
   correcting common errors encountered along the way.

   For additional information consult the "PWB/UNIX  User's  Manual"
   (obtainable  from  your system administrator or from Joe Clemmons
   at 4734s).

   The PWB/UNIX User's Manual contains the in-depth  information  on
   commands,  system  calls, file structure and protection, and file
   formats needed for systems programming endeavors.

   For technical assistance or general questions consult your system
   administrator or someone from the UNIX Support Group.






























                                 - 1 -






                                  TUG

   1.  INTRODUCTION



   1.1.  What is UNIX?

   UNIX is a general-purpose, multi-user, interactive operating sys-
   tem  developed  by  Bell Laboratories. It is currently run on the
   Digital Equipment Corporation's 11-series computers  as  well  as
   the  machines  of  several other manufacturers.  It was initially
   designed for research in operating systems, languages and a  host
   of  other  topics.  However,  it  has  been  put to use in a wide
   variety of ways, among which text preparation  occupies  a  prom-
   inent place.

   The original version of UNIX was introduced in 1969. The  version
   which is currently being used within the Agency is a revised ver-
   sion that was released by Bell Laboratories in February 1971.  As
   a result of this revision, UNIX is presently  a  system  of  many
   unique capabilities. It contains  a  number  of  features  seldom
   offered even in  much  larger  systems, such as:

       o+   it allows use of upper and lower-case characters as  well
           as special characters in the formation of file names.
       o+   files are created directly at the terminal with very lit-
           tle effort.
       o+   it allows a file to be created by alternate methods.
       o+   it has several facilities which may be  used  to  edit  a
           file.
       o+   it performs many functions  by  just  using  a  few  keys
           rather than having to type a complete input line.
       o+   it has a  symbolic command language that is easy to use

   There are many other unique features which could be  cited;  how-
   ever,  we hope you will find that the most important characteris-
   tics of UNIX are its simplicity, elegance, and ease of use.

   Primary utilization of UNIX is the preparation and formatting  of
   documents and textual materials, and software for other systems.

   UNIX supports some common computer languages such as FORTRAN  and
   BASIC  as  well  as some esoteric languages such as C, PASCAL and
   LISP.  Also, there are a variety of games availabe on the system.
   They  range in complexity from simple games like hangman and tic-
   tac-toe, to a multi-player world conquest game called EMPIRE.








                                 - 2 -







                                  TUG

   1.2.  Where is UNIX?


   Several UNIX systems are located at both the Operations  Building
   and FANX. Most of these systems support terminal rooms as well as
   terminals in the offices of regular users. A  terminal  connected
   to ELROND is located in the FANX Learning Center. UNIX documenta-
   tion is close at hand for most of the "public terminals."   Also,
   persons  familiar  with UNIX are not hard to find and are usually
   more than willing to provide assistance.

   1.3.  Network Facilities


   Most UNIX systems permit users access to a network  of  intercon-
   nected  systems. If you feel that you can profitably use the net-
   work facilities get in touch with your system  administrator.  He
   should  be  able  to secure access privileges for you and provide
   user documentation relating to the network.

   1.4.  How to Get an Account


   Prospective users must submit an application for  an  account  on
   the system.  If the application is approved, the new user will be
   issued a login name and login password, and will be assigned to a
   group.  Each user should know his group ID, user ID and the names
   of the other members of his group. For information about changing
   groups,  finding  groups  and  adding members, consult the system
   administrator.

   Each user is assigned a  login  directory  and  is  empowered  to
   create  additional  directories.  The user assumes responsibility
   for the contents of his directories from both  the  security  and
   housekeeping  standpoints. Details concerning the user's security
   responsibilities will be discussed in a section of this document.
   The  user's  housekeeping  responsibilities  are  straightforward
   enough - junk files should not be allowed  to  accumulate.   Some
   housekeeping  functions are performed by the system itself. There
   exists a program called the "midnight  skulker"  which  automati-
   cally  deletes  all  user  files named a.out, *.o, *.bak, .{* and
   core  that have not been used in the past fourteen days.

   1.5.  UNIX Security


   In order to maintain a high level of security:

       o+   Each user should change his  password  immediately  after
           getting  a UNIX account, and thereafter at least monthly,
           or whenever a  password  is  compromised.   In  order  to
           change  a  password,  type "passwd", the system will then

                                 - 3 -







                                  TUG

           prompt for the old and the new passwords, and record  the
           change.   Please  note that passwords must have a minimum
           of five characters, and should not be easily derived.  Do
           not  use your phone number, license plate, spouse's name,
           or birth date as a password.

       o+   Users should understand the meaning of modes  of  protec-
           tion  and  ownership  for  both ordinary files and direc-
           tories.  All files may be created readable by users other
           than the owner, and will remain readable unless the owner
           takes explicit action to  change  the  read/write/execute
           privileges.   The command to change file mode is "chmod";
           a full explanation of available options can be  displayed
           by typing "help chmod".

       o+   Since files can be created readable it is  important  for
           all users to realize that every unprotected file could be
           read by anyone on the PLATFORM  network  (i.e.,  contrac-
           tors,  employees involved in other projects, thrill seek-
           ers, idle browsers, etc.).  The user  must  take  precau-
           tions  to secure classified, or otherwise sensitive, data
           which is on the system, just as he would  to  secure  any
           other classified or sensitive information.  Since systems
           vary in terms of clearance levels, the  user  must  check
           with  the systems administrator to find out the clearance
           level for a specific system.

       o+   Line printer output which is classified must be so desig-
           nated  by  the user.  The "opr" command used to print out
           files has a -_C"_c_l_a_s_s_i_f_i_c_a_t_i_o_n" option  which  prints  the
           desired  classification on the burst page.  An example of
           this is _o_p_r -_C"_h_u_s_h-_h_u_s_h" [filename].   Classified  list-
           ings  should  be  picked up promptly, and the user should
           take care to pick up only his own listings.

   1.6.  Consulting and User Assistance


   The user's first source of assistance is the systems  administra-
   tor.  If the systems administrator is unable to resolve the prob-
   lem, contact one of  the  Agency  gurus.   Mr.  Howard  Rumerman,
   T3332,  4052s,  will  be able to give the name of someone who may
   help you.

   If the problem does not require immediate attention, try the mail
   program.   The  following  names are standard and should get some
   response:


       o+   gripe  - complaints regarding operations  or  administra-
           tion


                                 - 4 -







                                  TUG

       o+   system - general complaints about the software


       o+   guru   - complaints of a serious nature with wide impact

   The "who" and "write" commands that are discussed below can often
   be  helpful  in  getting  immediate  assistance from other users.
   Look for the login names root, bin, or unix.

   1.6.1.  Terminal Malfunctions

   Occasionally, terminals are known to  misbehave.   In  the  event
   that the terminal does not recognize or respond to commands typed
   on the keyboard, or does not prompt for a login:


       o+   Check to see that the terminal is turned on, plugged  in,
           and connected to a comm line.

       o+   Check to see if the terminal has  gone  off-line,  if  it
           has, depress the on-line button on the upper right of the
           keyboard to get back on-line.

       o+   If the terminal is  on-line,  hit  the  break  key,  then
           return.   If  after  several  attempts  there is still no
           response, turn the terminal off, turn it  back  on  again
           and try to log-in. For persistent problems contact opera-
           tions.

   For further information, read the Programmer Information Bulletin
   entitled,  "The  Care and Feeding of Terminals" (see sec 4.4.1 of
   this doc.) and Chapter 7 of the  PWB/UNIX  User's  Manual,  which
   contains descriptions of each terminal type.

   1.7.  On-line Documentation Aids


   In addition to the printed documentation described below in  sec-
   tions 1.8, 1.9 and 1.10 a considerable body of UNIX documentation
   is kept on-line.  Also, there are systems programs  available  to
   produce  copies  on  your terminal, etc..  If you are not using a
   hard copy terminal, the material will whiz by on the  CRT  screen
   too  fast  to  read.   For  this reason, when any of the commands
   discussed in this section are issued, add  the  command  "br"(for
   browse)  as  a filter. This will allow you to view the output one
   page at a time. The exact manner in which the browse  command  is
   used is illustrated in the following section.






                                 - 5 -







                                  TUG

   1.7.1.  The UNIX Manual

   The user's manual is kept online so that the user may gain access
   to it at any time.  To do so the user must type in this line:

        man [chapter in which your topic is located] [topic].

   An example of this is the following:

                          man 1 who

   which will give the user the manual page of the "who" command  in
   chapter I.  As noted above, to view the output one page at a time
   you use the "br" command as a filter:

                         man 1 who | br

   To obtain a copy on the line printer one types:

                         man 1 who |opr

   To obtain a copy of the table of contents use the following  com-
   mand with the "opr" or "br" filters as desired:

                         man 0 toc

   Note: (a)The use of filters or pipes is explained in some  detail
            in  section  3.6.2.  Essentially,  a pipe will cause the
            output of the program to the left of the pipe to be used
            as input to the program to the right of it.
         (b)The last character on each command line must be the new-
            line  character,  which is entered by hitting the RETURN
            key.  For the sake of simplicity, the newline  character
            will  not be included in the examples in this text. How-
            ever, the user should keep in mind the  fact  that  com-
            mands are not executed until the RETURN key is hit.

   1.7.2.  Help

   A second on-line aid is the  "help"  command.   This  command  by
   itself  will  display a list of topics for which helpful informa-
   tion is available. Help on a specific topic can  be  obtained  by
   using the command with the topic as an argument.  For example:

                            help fortran

   For help in correcting errors the user should use the "help" com-
   mand in the following fashion:

                          help [error number]



                                 - 6 -







                                  TUG

   For further  information  read  the  description  of  "help"   in
   chapter I of the manual.

   1.7.3.  News

   A third on-line aid is the "news" command. Like the  "help"  com-
   mand,  if  the  user  types "news" a list of available news items
   will be displayed.  By entering a command of the  following  gen-
   eral form:

                             news [item]

   information on any one of a number of  available  topics  can  be
   obtained.

   1.7.4.  Other manuals and documents

   On-line documentation exists for manuals and Programmer  Informa-
   tion  Bulletins  (PIB).   To  obtain  printed  copies contact the
   operations staff, or, Joe Clemmons, T12.

   1.7.4.1.  Documents and User Manuals

   There are several specialized manuals maintained on-line.   These
   manuals  are  of  less  wide-spread  interest than the major UNIX
   manuals.  They cover a specific software product with more detail
   than  the  UNIX  manual page.  The manuals available at this time
   are the following:

        []  bas       - The UNIX basic manual
        []  ded       - Directory Editor (Graphical Shell)
        []  f4p       - FORTRAN IV Plus
        []  fortran   - RT-11 FORTRAN IV
        []  lisp      - Univ. of Md. Lisp Interpreter
        []  ms        - UNIX Mail System
        []  roff      - Runoff (ROFF) Tutorial
        []  tbl       - Manual on the tbl program
        []  trekman   - Star Trek (UCB Version)
        []  wbs       - Work Breakdown Structure
                            (Project Management)

   These manuals can also be obtained from operations.

   The command "doc [manual name]" will cause a copy of  the  manual
   to  be  displayed on your terminal.  The argument, "manual name",
   is selected from the list of available manuals.

   Note: the doc command will cause the document to  appear  on  the
         screen via a scrolling up action that is without pauses. To
         cause it to appear a page at a time the program  should  be
         piped to the br program.


                                 - 7 -







                                  TUG

   1.7.4.2.  Programmer Information Bulletins

   Programmer Information Bulletins (PIBs) are used to provide short
   notes  and  details on some esoteric features of UNIX.  They also
   are used to provide information on  items  of  general  interest.
   The  following  Programmer Information Bulletins are available as
   of the distribution date of this terminal user's guide:

        pib-76-002      The Care and Feeding of Terminals
        pib-76-005      USERS' GUIDE TO THE "EM" MACROS
        pib-76-006      UNIX/H-6060 File Transfers
        pib-76-007      UNIX <--> 370 Tape File Transfers
        pib-76-009      An Abecedary to Xeroxing
        pib-76-011      RJE Status Commands for the 370
        pib-77-002      Improvements in the Rand Editor
        pib-78-001      Application for Account on UNIX
        pib-78-002      Version 7 C Compiler
        pib-78-003      Information for C Programmers
        pib-78-004      Information Guide For UNIX
        pib-78-005      FORTRAN IV Plus for UNIX
        pib-78-006      User's Guide to the "NM" Macros
        pib-78-007      Supplement to the UNIX Manual
        pib-78-008      8080 Cross Assembler
        pib-78-009      NROFF/TROFF
        pib-78-010      PORTS

   To obtain a list of Programmer Information  Bulletins  type  "doc
   pib" and a list will be displayed on your terminal.

   To obtain a given bulletin type "doc pib [yy ###]", where  yy  is
   the year and ### is the number of the bulletin.

   1.8.  UNIX Documentation

   Each user should have the following documents:

   1.8.1.  The PWB/UNIX User's Manual

   "The PWB/UNIX User's Manual" consists of 10 chapters of  which  8
   are  available  in hard copy (the other two are on-line).  Review
   the manual material to familiarize yourself with its contents and
   style.  Read the forward and introduction.  The table of contents
   will give a list of available system programs, monitor calls, and
   library  routines.   A  permuted  index is useful for finding the
   correct entry for a page.








                                 - 8 -







                                  TUG

   The chapters are arranged by topic in the following manner:

           Chapter         Topic

           I               Commands
           II              System Calls
           III             Subroutines
           IV              Special Files (Devices)
           V               File Formats and Conventions
           VI              User Maintained Programs
           VII             User Maintained Subroutines
           VIII            System Maintenance
           IX              FORTRAN IV Plus
           X               INGRES

   1.8.2.  Documents for the PWB/UNIX Time-Sharing System

   The "Documents for the  PWB/UNIX  Time-Sharing  System"  contains
   information on the following topics:

        PWB/UNIX Documentation Roadmap
        PWB/UNIX - Overview and Synopsis of Facilities
        The UNIX Time-Sharing System
        The Unix Time-Sharing System - A Retrospective
        UNIX for Beginners
        A Tutorial Introduction to the UNIX Text Editor
        Advanced Editing on UNIX
        PWB/UNIX Shell Tutorial
        NROFF/TROFF User's Manual
        PWB/MM - Programmer's Workbench Memorandum Macros
        PWB/UNIX Manual Page Macros
        Typesetting Mathematics - User's Guide(Second Edition)
        C Reference Manual
        Programming in C - A Tutorial
        A General-Purpose Subroutine Library for PWB/UNIX
        A New Input-Output Package

   It must be emphasized that the documents listed  above  represent
   only a cross-section of those available in the "Documents for the
   PWB/UNIX Time-Sharing System." For a full listing the user should
   consult the document's table of contents.

   For the beginner intent on making his way through  the  documents
   the  entry  "PWB/UNIX  Documentation  Roadmap" constitutes a good
   starting point. Two other documents that  the  novice  UNIX  user
   should  consult  are "UNIX for Beginners" and "Tutorial Introduc-
   tion to the UNIX  Text Editor."






                                 - 9 -







                                  TUG

   1.8.3.  Supplement to the PWB/UNIX User's Manual

   The "Supplement to the PWB/UNIX User's  Manual"  contains  manual
   pages  which are to be added to or replace pages in the "PWB/UNIX
   User's Manual".  These reflect changes to  existing  software  or
   software  added  to  the UNIX systems since the original software
   was distributed by Western Electric.  Included are a new Table of
   Contents  and  a  new  Permuted  Index,  both  of which should be
   scanned carefully, since they may be the  only  way  older  users
   become aware that potentially useful software has been installed.

   1.8.4.  UNIX Reference Card

   The UNIX Reference Card is a handy list of UNIX commands (includ-
   ing NROFF and TROFF), which provides a brief description of every
   command it contains.  It is an excellent  short-cut  for  finding
   commands,  but  it  is no match for the User's Manual in terms of
   detail and completeness.  Also note that the URC dates from l975,
   and  does  not  reflect  more  recent  modifications  made to the
   software.

   1.8.5.  GTSS Documentation

   There are a variety of GTSS documents that can be  obtained  from
   Joe  Clemmons  of T12. The following documents relate to Platform
   network use:


       1.  User Telnet (GTSS Document #5) - This is a  user's  guide
           for  the  user  telnet  program. User telnet allows local
           users to access portions of the Platform network.

       2.  User's Manual for UNIX Controller FTP (GTSS Document  #4)
           -  This  document  specifies the commands that are recog-
           nized by the controller for file  transfer  protocols  as
           well  as  what responses are to be expected from the con-
           troller.

       3.  User's Manual for UNIX File Handling - File Transfer Pro-
           tocol  (GTSS  Document  #2) - This document specifies how
           the File Handling - File  Transfer  Protocol  program  is
           used in transfering files across the Platform network.

       4.  GTSS Software Manual (GTSS Document  #1)  -  This  manual
           documents  the  software which comprises the current ver-
           sion of the Generalized Terminal Subsystem (GTSS).

   Additional GTSS documentation is available on topics that are  of
   a more specific nature and/or less widespread utility:




                                - 10 -







                                  TUG

       5.  Data Entry and  Display  Subsystem  User's  Guide  (DEDS)
           [GTSS  Document #6] - This document is intended to show C
           Language programmers how to display formatted data on the
           terminal  screen and store data for later retrieval using
           the DEDS software package. (Warning: DEDS does  not  work
           on all terminals)

       6.  TSQUARE: Terminal Subsystem for Query and Retrieval (GTSS
           Document  #3) - This document serves as a user's guide to
           TSQUARE. The originators of TSQUARE describe it as a mod-
           est UNIX-based query and retrieval system.

       7.  Platform FTP User and Technical Manual  -  This  document
           specifies  the  commands  that are recognized by the File
           Transfer Protocol program.*

   * Platform FTP is currently being phased out  in  favor  of  Con-
   troller FTP


   1.9.  Advanced Reading


   The documentation described in the previous section  is  insuffi-
   cient  for  those  who  want  to write their own programs in C or
   assembler, or who intend to do serious work  in  the  writing  of
   manuals, reports and other kinds of documents.

   1.9.1.  Text Processing

   People working with the preparation of documents should begin  by
   consulting  Section  T  of  the "Documents for the PWB/UNIX Time-
   Sharing System" (several of the entries in this section have been
   referenced  above).  Two entries in this section are particularly
   useful: "NROFF/TROFF User's Manual" and "Typing Documents on  the
   UNIX  System:  The -ms Macros for TROFF and NROFF." Another macro
   package used in conjunction with NROFF is documented in  the  on-
   line  PIB: "USERS' GUIDE TO THE "NM" MACROS"(PIB-78-006) There is
   also a manual  page  for  each  macro  set:  "MM(I)",  "MS(VII)",
   "TMAC.NAME(VII)", and "MNM(VII)".

   1.9.2.  Programming

   People planning to write programs for UNIX  should  learn  the  C
   language.  A good place to start is with the book "The C Program-
   ming Language" by Kernighan and Ritchie,  (Prentice-Hall,  1978).
   Copies  of  this are available in the Central Library.  There are
   two PIB's available ( PIB-78-002 and PIB-78-003 ) which give use-
   ful information on C programming.




                                - 11 -







                                  TUG

   C-related topics are covered in two entries in  the  "Documents":
   "A  New  Input-Output  Package" and "A General Purpose Subroutine
   Library for PWB/UNIX."  Also,  chapters  2,3,4,5  and  7  of  the
   "PWB/UNIX  User's  Manual"  contain  information that is directly
   applicable to C programs.

   1.10.  Training


   Two courses are available through the Training School:

        []  A self-paced course on UNIX for the
            Beginner, MP-ll9
        []  A self-paced course on C programming, MP 220

   Other courses and seminars can be  organized  by  the  school  if
   there is sufficient need.  Contact your training co-ordinator for
   more details.  Special advanced seminars can  also  be  scheduled
   through T3332 if sufficient operational need exists.


































                                - 12 -







                                  TUG

   2.  Using UNIX



   2.1.  Using a Terminal


   2.1.1.  Putting the Terminal On-line

   Two types of CRT terminal predominate within  the  Agency's  UNIX
   community  -  the Delta Data 7000 and the Superbee. The procedure
   for going on-line vary between the two. For the Superbee only two
   steps  are involved. One must turn on the power (the power switch
   is located in the rear of the terminal, in the  lower  left  hand
   corner)  and  then hit the on-line key (top row, left side of the
   keyboard). If the login prompt doesn't appear hit the BREAK key a
   couple of times. For the Delta Data one must complete a series of
   "down-line loading" procedures. A set of instructions  illustrat-
   ing the process should be posted somewhere in the vicinity of the
   terminal.

   2.1.2.  Logging in

   Once the terminal has been put  on-line  the  login  prompt  will
   appear on the screen together with the computer name and the ver-
   sion of the UNIX operating system being run. Respond to the login
   prompt  by  typing your login name followed by a carriage return.
   When you have done this the system will issue a password  prompt,
   to  which  you respond by typing in your password.  Your password
   will not be echoed on the screen for obvious reasons.  Once  your
   login  name and password are verified the system will display the
   message of the day, the quote of the day and the like.  Following
   this  the  prompt character(%) will be displayed, indicating that
   you are talking to the UNIX command interpreter (i.e. the shell).

   If you receive a response such as "no directory,"  notify  opera-
   tions.   If  you  receive  a  response of "Permission denied," it
   means that you are not authorized to use the particular  terminal
   you're  trying  to  log onto.  Try another terminal or ask opera-
   tions or the system administrator to give you  access  rights  to
   the  terminal,  (assuming  that  it's  a  terminal  you should be
   allowed to use).

   If the system responds to your attempt to log in with the message
   "login  incorrect:"  you  have  made an error in typing in either
   your login name or your password. Repeat the login  procedure  in
   order to gain access to the system.






                                - 13 -







                                  TUG

   2.1.3.  Logging Out

   The UNIX shell will take commands to manipulate files and  invoke
   languages.  When  you  are  all  through running type "logout" or
   "detach." (Detach, in contrast to logout, will not kill jobs that
   are  running  "in background". More will be said about background
   jobs at a later point in the manual.)

   2.1.4.  Useful Information About Your Terminal

   There are two keys on the terminal which act like shift keys on a
   typewriter.  These are the shift key and the control key. To type
   a "control letter" hold down the control key and press the letter
   key.   Control  functions serve a variety of purposes on the sys-
   tem. For example CTRL-T, which is often  written  ^t,  will  echo
   "System  Status: Normal" if the system hasn't crashed on you. The
   shift key works the same way on a terminal  as  it  does  on  the
   typewriter. It is the means of typing upper case letters and many
   special characters.  When using the shift key one should be care-
   ful  to avoid hitting the shift lock. This is a common problem on
   both the Superbee and Delta Data terminals.

   2.1.5.  Several Common Problems

   If your terminal is typing only in upper case  letters  check  to
   see  that  you have not accidently hit the shift lock key. If the
   shift lock is not on and you are locked into upper case  type  in
   "stty  -lcase"  (it  will appear on the screen in upper case) and
   you will be returned to lower case.  Alternately,  you  can  free
   yourself from upper case by logging out and then logging back in.

   There are a whole range of terminal problems which can  crop  up,
   most  of  which are not amenable to a quick and easy solution. If
   you find that your terminal is acting up you should  notify  your
   system  administrator.  He  will  be able to notify the person(s)
   responsible for terminal maintenance.

   If you suddenly find that the characters you are typing  are  not
   appearing  on  the  screen it may be that the system has crashed.
   You can check on this by firing off a quick call to  your  system
   administrator or by hitting CTRL-T. If the system has not crashed
   CTRL-T will return the following message:  "System  status:  Nor-
   mal." Obviously, if the system has crashed you'll get no response
   from CTRL-T. As you can well imagine the latter method of  check-
   ing  for  a  system  crash  is considerably easier on your system
   administrator's peace of mind. If the system has crashed, hit the
   clear  key  to  clear  the screen ( a good idea from the security
   point of view) and wait for the login display to reappear. (Note:
   the  clear function key is available only on Superbee terminals.)
   If you were using the RAND Editor at the time of the crash  there
   is  a way to (sometimes) recover the work done during the editing
   session. The following sequence of commands:

                                - 14 -







                                  TUG

                  % cp /tmp/rettyx.login-name retty
                  %editor -retty

   will usually cause your editing session to  be  reproduced.  (You
   must substitute your terminal number for "x" in the above command
   and your own login name for "login-name.")

   2.2.  The Printer Terminals


   Three types of printer terminal are used  with  Agency  computers
   running  UNIX:  the  Anderson Jacobson 832, the Qualterm X100 and
   the GSI 300Q. These terminals are used to obtain hard copy  which
   is  of  a  better  quality  than that produced by a line printer.
   They produce print which is equivalent to  typewriter  print  and
   can use either standard line printer paper or typing paper.

   When using the printer terminals it is essential that  modes  and
   speeds  be properly set using the "stty" command. Thus, if moving
   from a CRT (which runs at 2400 baud) to an AJ 832 (which runs  at
   300  baud)  a  command of the following sort should be entered on
   the CRT:

                          stty 300 -tabs

   The "-tabs" argument sets UNIX for software tabs, which will  get
   you  around  the  problem  of the printer terminal not having its
   hardware tabs set. Alternately, you could set the  hardware  tabs
   on  the  printer  by  typing  the following command once you have
   moved to the printer terminal:

                               tabs

   Now we are prepared to consider what you do  once  the  move  has
   been made from the CRT to the printer terminal.

   The three types of printer terminal work in essentially the  same
   way  and  the  operating  procedures  are not overly complicated.
   Assuming that you are working with an Anderson Jacobson  that  is
   on-line  and  has  its switches properly set, you can print out a
   formatted document by entering a command of the following sort:

                     nroff -T832 -s filename

   This should be typed on paper that is not part  of  the  document
   and  <carriage  return>  must  not be entered until new paper has
   been inserted.  The "-T" argument indicates to the text processor
   (i.e.  nroff)  the type of printer terminal that is being used so
   that it can take advantage of its features. The following are the
   "-T" arguments for the three types of printer terminal:



                                - 15 -







                                  TUG

                  -T832.....Anderson Jacobson 832
                  -T100.....Qualterm X100
                  -T3000....GSI 3000

   The "-s" argument will cause the printer to stop at  the  end  of
   each page, allowing a new sheet of paper to be inserted. Once new
   paper has been entered you must hit <carriage  return>  again  to
   begin printing.

   For more information on using the printer terminals  it  is  sug-
   gested that the user consult the following documentation:


       o+   "The Care and Feeding of the AJ," (a  "PIB  in  the  mak-
           ing").

   2.3.  Special Characters


   2.3.1.  Editing Typing Mistakes

   If an error is made while typing in a  line,  there  are  several
   control characters designed to help you undo the error:

   #----Erases the last character typed.  Successive  uses  of  this
        control  character  will  erase  characters back to, but not
        beyond the begining of the line.

   @----Erases all characters that precede it on the line. To remind
        you the terminal will move the cursor to a new line.

   2.3.2.  Controlling Typeout

   There are two keys which serve the function  of  controlling  the
   flow of output to the CRT screen:

   CTRL-S----This key suspends output. It is particularly useful for
             giving the user time to read what is being displayed on
             a CRT screen. If the user does not  hit  CTRL-S  output
             will  quickly  pass  off  the  screen  in  a continuous
             "scrolling up"  action.  (The  scrolling  up  continues
             until the end of the output is reached.)

   CTRL-Q----This key will cause the flow of output to be  continued
             from the point at which it was interrupted.








                                - 16 -







                                  TUG

   2.3.3.  Interrupting a Command in Progress

   At certain times it may be useful to terminate a  command  before
   it  acccomplishes  what  it was intended to accomplish. There are
   three ways of terminating a command that apply to different  sets
   of "terminating circumstances:"

   RUB OUT---This key terminates the current command, and returns
   DELETE    control to the shell, with a few exceptions. For  exam-
             ple,  if  a  command is given to type a file, and after
             the first few lines you don't want  to  see  the  rest,
             then  type  RUB OUT and you will receive another prompt
             sign(%). In some languages, such as BASIC and PPL,  RUB
             OUT  is used to interrupt infinite loops, and return to
             the language's command level.

   CTRL-\----This key has the same effect as RUB OUT,  but  it  also
             produces  a core dump file of the running command. This
             key should only be used when you are debugging  a  pro-
             gram  of  your  own  and want to save a core image. The
             resultant CORE file can be examined using  "db,"  "adb"
             or  "cdb" (see the UNIX manual and the write-up in sec-
             tion 4 of this document).

   PANIC-----The PANIC key is the most general means of  terminating
             a  command  in  progress  -  it  works  under  all cir-
             cumstances. It is, however, the  most  drastic  way  of
             terminating a command. Rather than returning control to
             the command level it logs  the  user  off  the  system.
             Thus,  PANIC  is  best reserved for situations in which
             nothing else will work. (Note: to make  PANIC  work  it
             may  be necessary to hit the key twice in quick succes-
             sion.)

   2.3.4.  Terminal End of File

   In the interactive mode an end of file is marked in the following
   fashion:

   CTRL-D----This key when typed at the begining of a line  has  the
             effect  of  producing an end-of-file from the terminal.
             Programs which process their  input  until  they  reach
             end-of-file  can be typed into directly by ending input
             with CTRL-D.

   2.4.  Upper-Lower Case


   The UNIX system was designed for full character terminals  (i.e.,
   terminals with upper and lower case letters), on which it is much
   easier to type commands in lower case.  To enable terminals which
   type only upper case to use the system, one of the terminal modes

                                - 17 -







                                  TUG

   which is supported by UNIX causes all upper case characters to be
   translated into lower case.  This means that the upper case char-
   acters you see on your terminal are actually being  seen  by  the
   programs  on  the  system as lower case.  For this reason, all of
   the documentation on UNIX uses lower case when talking about typ-
   ing in and receiving output from the system.

   It is possible to enter an upper case character to the system  by
   preceding  it  with a "\".  This allows a user to type full upper
   and lower case from a terminal which has only capital letters.


   2.5.  Files


   The concepts of files and directories are familiar to anyone  who
   has used time-sharing before, but for anyone who is used to batch
   computing which uses cards for input, these terms  will  be  new.
   UNIX  users  are  assigned  a particular directory which contains
   their files.  A file is simply text or data with  a  unique  name
   within a particular directory.

   Imagine the file structure as being a library.  Users have  their
   own  private  stacks (directories) in which they keep their books
   (files).  Each book in a users stack must have a different  name,
   but  many  users may have the same book in their own stacks.  Any
   book in the library can be described by its stack and  its  name,
   and  in  the UNIX system, any file can be specified by its direc-
   tory and its name.

   Although the name of a stack and book is sufficient to identify a
   unique  book  in  the  library, it is necessary to know where the
   stack is in order to actually find the book.  The set of instruc-
   tions,  or  map, leading to a particular file (stack and book) is
   called its "pathname".  If users wish to reference a  file  which
   is  not  in  their directory, they must specify the path from the
   beginning of the file structure to the individual file.  At  each
   directory  along  the  way,  the  proper path to the file must be
   chosen from among the subdirectories and other files within  that
   directory.   For  example,  the path "/usr/games/hangman" directs
   the system to start at the beginning of the file  structure  (the
   leading  "/"), go to the directory named "usr", within "usr" find
   the directory named "games", and  therein  find  the  file  named
   "hangman".

   Files have several attributes of interest as well as their names.
   Each file has a length which is measured in bytes.  Each byte can
   contain a single character, or 8 binary bits of information.  The
   physical device which contains the files (called a "disk") organ-
   izes information in chunks of 512 bytes, so files are  quantified
   in  blocks of 512 characters.  Thus, a file less than 512 charac-
   ters long takes up one block, 513  up  to  1024  characters  long

                                - 18 -







                                  TUG

   takes  up  two  blocks,  and so on.  For files of more than eight
   blocks, there is an extra block of overhead for every 256  blocks
   of the file.  See the "PWB/UNIX User's Manual" for more detail.

   For purposes of accounting, file sizes are  measured  in  blocks.
   The total number of blocks your files and directory are using can
   be found using the "du" command described below in the section on
   UNIX information commands (sec. 3.7.1).

   Another attribute of a file  is  its  "protection".   This  is  a
   facility  which allows you to give other users either free access
   to your file, or  access limited as you desire.  See the  "chmod"
   command described below (sec. 3.7.3) for more information on file
   protections.

   2.6.  File Names and Wild Cards


   File names on UNIX are up to 14 characters long, and composed  of
   any  characters.   Do  NOT  use  "."  as the first character of a
   file-name, since the system utilities for cataloging  files  will
   not  list  such  files.  In addition, the file-names "." and ".."
   are reserved for system use.  (See the PWB/UNIX User's Manual.)

   In naming files certain conventions are usually observed so  that
   the  nature  of  the file can readily be discerned from its name.
   The convention followed on UNIX is to end the  file-name  with  a
   period  followed  by  a few characters which indicate the type of
   the file.  These suffixes are called extensions, and a few common
   ones on UNIX are:

             filename.ppl     a source file for PPl
             filename.f4p     a source file for FORTRAN
             filename.bas     a source file for BASIC
             filename.dat     a data file for FORTRAN or BASIC
             filename.bak     a source file backup
             filename.c       a source file for the C language

   It is often inconvenient to type complete  file  names,  particu-
   larly  if  the  same action is to be performed on many files.  To
   simplify the specification of filenames, certain "wild cards" are
   allowed  which  can  be  used in order to make a single string of
   characters refer to many files when they are typed to the  shell.
   These "wild card" characters are:

   *         "*" matches any string of characters.  Thus  "*"  alone
             is  all  file-names in your directory.  "foo*" would be
             all file-names beginning with "foo", and so on.

   ?         "?" matches any single character.  Thus  "?"  alone  is
             all file-names one character long.  "foo?" would be all
             file-names four characters long beginning with "foo".

                                - 19 -







                                  TUG

   [         "[xyz]" matches just the characters "x", "y"  and  "z".
             "[a-g]"  matches any single character from  "a" through
             "g".  Thus "foo[abc]" describes the file-names  "fooa",
             "foob", and "fooc", and is equivalent to "foo[a-c]".

   Some examples of wild cards using the rm command are:

   rm *.ppl            this deletes all  files  with  the  extension
                       "ppl" e.g., file1.ppl, text.ppl, a.ppl

   rm *                this deletes all files (so be careful)

   rm file?.bas        this deletes file0.bas, file1.bas, filez.bas,
                       etc.,  but  does  not  delete  file1a.bas  or
                       file.bas

   rm file[a-s].bas    this deletes filea.bas, filec.bas, etc.,  but
                       does not delete file1.bas or filet.bas

   Note: (1) It doesn't make sense to use wild cards for destination
             files.   Wild  cards  are useful in referring to files,
             but they can never be used to make new files.

         (2) When you try to delete several files with the "*" wild-
             card you will be presented with a request for confirma-
             tion.  This takes the following form:

                           glob: [Confirm]

             If you wish to confirm, type y  and  hit  the  carriage
             return;  if  not,  type n and hit return. The action is
             carried out only after confirmation is received.





















                                - 20 -







                                  TUG

   3.  The UNIX Shell



   3.1.  What is the UNIX Shell?


   On UNIX the standard command interpreter is called the UNIX Shell
   (or simply the "shell").  This is a program which interprets your
   typed commands and issues the appropriate system requests to have
   the  commands  executed.   The  shell  has  been designed to make
   interaction with UNIX as simple as possible and to prevent  users
   from making careless mistakes.

   3.2.  Command Format


   When the shell is ready to accept commands it  types  the  prompt
   "%" followed by a space.

   The general format of shell commands is:

           % command-name argument argument . . .argument<nl>

   The "%" is typed by the shell and  the  user  types  the  command
   name,  a space, and then any arguments to the command.  The argu-
   ments are separated  from  each  other  by  a  space.   The  <nl>
   represents  a  newline  character which is appended to the end of
   the command line by hitting the carriage return.  It serves as  a
   signal  to the shell that the command is complete and that execu-
   tion may begin. As noted above, it will not be included in forth-
   coming command examples.

   As an example of how UNIX shell commands work consider  the  fol-
   lowing command:

                        % mv automobile car

   This is the "mv" command (short  for  move)  with  the  arguments
   "automobile"  and  "car".  Here the arguments are file names, and
   the "mv" command changes the name of  the  file  "automobile"  to
   "car"  (by  moving the first file to the second and then removing
   the first one).

   Consider the following command:

                             % date






                                - 21 -







                                  TUG

   This is the "date" command which requests the date and time.  The
   command  has  no  arguments.  After the user types the above, the
   system responds

                  Thu Feb 7  12:57:57  EST 1980
                  %

   The computer has typed the date and time, as requested,  followed
   by  a  new  prompt,  telling the user that the system is ready to
   accept another command.

   Several commands may be typed  on  a  single  line  if  they  are
   separated by semicolons.

   3.3.  Command Abort


   A command can be aborted by typing "@" (see sec.  2.2.1)  at  any
   time  before typing the final <nl> which actually starts the exe-
   cution of the command. The system starts on a new line  to  indi-
   cate that the command was aborted.  RUBOUT and BREAK will usually
   have the same effect as "@," but "@" is the preferred  method  of
   aborting a command.

   3.4.  Help: Requesting Information on Various Topics


   3.4.1.  Help: The Shell Program

   "Help" is a shell program which provides information about a wide
   range  of  UNIX  commands,  system  calls,  programs, programming
   languages and games. The format of the help command, which  could
   not be more simple, is as follows:

                           help <topic>

   You can obtain a list of the topics with which the  help  command
   can  be  used  by  typing help (followed, of course by a carriage
   return).  With a small group of programs (telnet,  pftp-srvr  and
   pftp-user) the format of the help command is slightly different:

                       help <program> <topic>

   As an example of how the help program works consider the  follow-
   ing.  The command:

                         help telnet tenex

   will produce the following display:




                                - 22 -







                                  TUG

   ______________________________________________________________
   |[set]  tenex                                                 |
   |           Purely  a  convenience  command,  this  puts   the|
   |           terminal  into  charmode  with local echoing off -|
   |           the preferred mode for TENEX connections.  See the|
   |           `charmode'    and   `echo'   commands,   and   the|
   |           elaboration on connections for more detail.       |
   |_____________________________________________________________|

   Though help seldom returns a detailed response to your query, the
   response is adequate for most purposes.

   3.4.2.  The Help Feature Built-In

   Some of the programs that run on UNIX have the help feature built
   into  them.  By  typing a question  mark in response to a prompt,
   the system will display a list of commands that can be used  with
   the  program. The built-in help feature can be illustrated by the
   msg program. In response to the  command  "msg,"   the  following
   display will appear:

   _____________________________________________________________
   |Readmail -- version 2.3 of 3/2/79                           |
   | 1   160 char  1 Feb 1980 elrond at ELROND "password change"|
   |1 message                                                   |
   |For help type ?                                             |
   |->?                                                         |
   |                                                            |
   |Commands are:                                               |
   |b[ack-up and print message]                                 |
   |c[urrent message is] <message no> in file <filename>.       |
   |d[elete] <message no>...                                    |
   |e[xit and overwrite current mail file to reflect deletions] |
   |                                                            |
   |____________________________________________________________|

   The list of commands has been abbreviated, since  what  is  shown
   above more than suffices for the purposes of illustration.

   3.5.  UNIX Shell Variables (*)


   The Unix shell employs twenty-six string  variables,  $a  through
   $z, which offer the user a means of storing information for quick
   retrieval. Retrieval is accomplished through a  simple  shorthand
   notation.   In general, shell variables can be used in two ways -
   interactively and as a component of shell programs. The manner in
   which  shell variables are used interactively will be illustrated
   below. The use of these variables in shell  programs  is  a  more
   complex  topic  which will not be covered here. At the conclusion
   of this section a short bibliography  of  documents  relating  to
   shell programming has been appended.

                                - 23 -







                                  TUG

   3.5.1.  Using Shell Variables Interactively

   Shell variables can be broken down into two categories. Those  in
   the  range  $a  through $m are initialized to null strings at the
   begining of execution and are modified  only  by   explicit  user
   request.  In the second category of shell variables, ranging from
   $n through $z, there are several that are given specific  initial
   values.  These values can in most cases be modified during execu-
   tion.

   3.5.1.1.  User-defined Shell Variables

   The way in which user-defined shell variables work is best illus-
   trated  by  practical  examples.  Suppose that you are frequently
   using several directories and would like to have an easy  way  to
   refer  to files in these directories. You can do this by defining
   the shell variables "$a" and "$b" in the following fashion:

                       = a /usr/tml/tug

                       = b /usr/tml/hold

   This is a simple assignment of a shell variable.  (Note:  if  the
   argument  that is being passed to "$a" contains any special char-
   acters it must be surrounded by quotes.) The information that  is
   stored  in  "$a" can now be recalled by a command like "echo $a",
   which will cause  the  contents  of  the  shell  variable  to  be
   displayed  on  the  CRT screen.  The same assignment of a current
   working directory to "$a" could be  accomplished  in  a  slightly
   different  fashion  by  piping  the  output of the "print working
   directory" program (pwd for short) to the variable.  This is done
   in the following way:

                            pwd | = a

   More will be said about the use of pipes in a section which  fol-
   lows.

   Before proceeding to a consideration  of  the  pre-defined  shell
   variables  it  should be noted that user-defined variables can be
   used as arguments to UNIX commands. For example, suppose you have
   the variables "$a" and "$b" defined in the following way:

                       = a /usr/tml/tug

                       = b /usr/tml/hold

   The following example of the copy command (which has the  general
   form: cp <old file> <new file>):

                     cp $a/chap1 $b/hold1


                                - 24 -







                                  TUG

   will cause a copy of the file chap1 in the tug  directory  to  be
   placed in the file hold1 in the directory named hold.

   As a final example of the use  of  user-defined  shell  variables
   consider the following:

                  cd /sys/source/s1/cref
                  pwd |= a
                  cd /pwb2/source/s1/cref
                  pwd |= b
                  ls -l $a/cref.c
                  ls -l $b/cref.c
                  ls -l $a/cref.c $b/cref.c

   3.5.1.2.  Pre-defined Shell Variables

   The shell variables with special meanings work in the same way as
   the  user defined variables. The only difference between the two,
   obviously, is that it is not necessary to assign arguments to the
   pre-defined variables. As an example of how the pre-defined vari-
   ables work consider the following:

                                $s

   This variable is initialized to the user's login  directory  (and
   as  a  result the login directory becomes the default directory).
   You can substitute this in a UNIX command  in  the  same  way  in
   which  you substitute user-defined shell variables. (For example,
   cp $s/chap1 $s/hold/hold1, with /usr/tml being the  login  direc-
   tory,  will cause the file "chap1" in "usr/tml" to be copied into
   the file "hold1" in "/usr/tml/hold".) It is possible for the user
   to  modify  most  of the pre-defined variables.  (For example, $s
   could be changed from the login directory to some other directory
   and that directory would then become the default directory.) This
   is a risky operation, however, because most  of  the  pre-defined
   variables were established for a reason.

   For a description of the full range of  pre-defined  shell  vari-
   ables  see the section entitled SH(I) in "PWB/UNIX User's Manual.
   The same material is covered in "PWB/UNIX Shell Tutorial" in  the
   "Documents for the PWB/UNIX Time-Sharing System."

   3.5.2.  Using the Shell Variables in Shell Programs

   As noted above a discussion of the  use  of  shell  variables  in
   shell  programming  is  beyond the scope of this user's guide. If
   the reader is interested in pursuing the topic of shell  program-
   ming it is suggested that the following documents be consulted in
   the order listed:




                                - 25 -







                                  TUG

       o+   "UNIX Time-Sharing System," Documents, see section 6

       o+   "UNIX for Beginners,"  Documents,  see  section  entitled
           "The Shell"

       o+   "SH(I)," "PWB/UNIX User's Manual"

       o+   "The Unix Time-sharing System - A  Retrospective,"  Docu-
           ments, see section entitled "User Interface"

       o+   "PWB/UNIX Shell Tutorial," Documents

   Note: "Documents" refers to "Documents  for  the  PWB/UNIX  Time-
   Sharing System"

   3.6.  Redirection of Input and Output and Pipes


   3.6.1.  Redirecting Input and Output

   Another very useful feature of the shell is  the  redirection  of
   input and output.  Most commands are written to use communication
   channels called the standard input  and  output.   Usually  these
   channels  communicate with your CRT. However, this may be changed
   so that the command reads input or  writes  output  on  the  file
   which  you specify.  To change the standard input add "<filename"
   to the command.  To change the standard output add ">filename" to
   the  command.   For  example, if you had a file named "input.txt"
   which  contained  the  input  for   a   fortran   program   named
   "prog1.out",

                     prog1.out <input.txt

   would use the file "input.txt" as the input to the program.   The
   command  "date  >output.txt" would put the response from the date
   command into the file "output.txt".

   The standard input and output are restored  after  the  command's
   execution.


   3.6.2.  Pipes

   Pipes are another very useful feature.  Typing a vertical  bar(|)
   between  two  commands means that the output of the first command
   is used as input to the next command.   For  example,  you  might
   want  a  line-printer copy of your output. If the file is execut-
   able, you simply type a command of the following sort:

                       toy.out | opr

   which causes a FORTRAN program to be executed and its output sent

                                - 26 -







                                  TUG

   to the line printer.  If the file is not executable it must first
   be directed to some program.  The output from  this  program  can
   then  be  piped  to  the line printer.  For example, consider the
   following command:

                       nroff junk | opr

   This directs UNIX to use the file "junk" as  input  to  the  text
   formatting program (i.e. nroff) and then "pipe" the output of the
   program to the line printer.

   3.7.  UNIX Commands


   In this section short descriptions of the most popular UNIX  com-
   mands will be presented.

   3.7.1.  Information Commands

   _q_u_e_s_t_i_o_n _m_a_r_k(?)

   "?" lists the complete set of UNIX commands.

   _h_e_l_p

   "help" is used to obtain  helpful  information  about  UNIX,  the
   shell, and various programs.

                              % help

   will list the available help topics.

                           % help snafu

   will list helpful information on topic "snafu".

   _w_h_o

   "who" lists the Lognames of the users logged onto the system.

   _w_h_e_r_e

   "where", with a terminal identifier as an argument, will  display
   the  location  of  the  specified  terminal.  For example, "where
   ttyp" will produce the following display:

                ttyp  A1D63 FANX 2 R812  7379

   which gives you the room number, building,  division  and  secure
   phone number associated with the specified terminal.



                                - 27 -







                                  TUG

   _n_a_m_e

   "name" will give  static  information  about  any  user  with  an
   account  on the system.  It expects a list of Lognames (see Login
   {II.1.E}) or last-names.  For example, "name tml" will yield  the
   following display:

                tml      R812    Thomas M. Leary

   which gives you the user's logname, division and full name.

   _d_a_t_e

   "date" responds with the current date followed  by  the  time  of
   day, e.g.

                  % date
                  Wed Feb 13 15:02:05 EST 1980

   _s_s

   "ss" (for system status) prints a list consisting of the  follow-
   ing  items:  the terminal identifier, the state of the particular
   process (run, slp, etc.), the user ID, the process ID, the prior-
   ity  of  the process, the size of the process, the amount of core
   time used so far and the command which initiated the process. The
   display generated by ss will resemble the following

   TTY STATE    UID    PID     PRI     SIZE     TIME  COMMAND
   p:  *slp     unix  2345   PSLEP   29+ 10     0:21  opr
   h:  *RUN*    tml     78     108        5     0:09  e expand.c

   _d_u

   "du" (for disk usage) gives the number of blocks contained in all
   files  and (recursively) directories within each specified direc-
   tory or filename. The response generated by the "du" command will
   resemble the following:

                  % du /usr/tml/tug
                  11       /usr/tml/tug/sys-6
                  122      /usr/tml/tug/training
                  1177     /usr/tml/tug

   The final figure represents the total number  of  blocks  in  the
   directory.  The preceeding two give the block totals for two sub-
   directories.






                                - 28 -







                                  TUG

   3.7.2.  Terminal Status

   _s_t_t_y

   "stty" (for set teletype) is used to set and test the  status  of
   your  terminal.  The command stty with no arguments will list the
   current characteristics of your terminal.

                speed 9600 baud
                erase = '#'; kill = '@'
                even odd -nl echo -tabs cr1
                Terminal type is Superbee Model 2

   The first line of the typeout contains the speed at which you are
   communicating  with  the  system. The second line lists the erase
   and kill characters that the system recognizes (coming  from  the
   type  of terminal that you are on). The third line lists the type
   of parity allowed(both even and odd in this case)  and  indicates
   that  a  carriage  return is allowed for a newline(-nl), that all
   characters typed are echoed  back,  that  tabs  are  replaced  by
   spaces  when  printing and that the delay for the carriage return
   is set for approximately .09 seconds(cr1). The fourth  and  final
   line  of  the  typeout  displays the system's idea of the type of
   terminal being used.

   _s_t_t_y [_a_r_g_u_m_e_n_t_s...]

   The stty command can be used with a set of arguments to set  cer-
   tain  I/O  options  on  the current output typewriter.  There are
   many characteristics which vary from terminal to  terminal.   For
   example,  some  terminals  have built in tab stops, and a special
   character directs the terminal to advance to the next stop.   For
   those  terminals  which  don't have this feature, it is necessary
   for the system to simulate a tab by expanding it into a number of
   spaces.   Also,  some terminals (such as the Delta Data 7000) can
   operate at a variety of speeds, and it  is  often  convenient  to
   speed them up or slow them down.  For a fuller explanation of how
   the stty command works and a list of valid arguments see  STTY(I)
   and STTY(II) in the "PWB/UNIX User's Manual."

   _N_o_r_m_a_l _m_o_d_e

   Many programs change some of the characteristics of the  terminal
   while  they are running.  In teco, for example, <esc> prints as a
   dollar sign.  If these programs complete in a normal fashion they
   restore  the  terminal to the state it was in before entering the
   program.  If, however, the program terminates abnormally, you may
   have  to  restore your terminal to its proper state.  This may be
   done by typing:

                          % stty normal


                                - 29 -







                                  TUG

   Your "preferred state" may differ from the "normal" one, necessi-
   tating additional changes.

   3.7.3.  File and Directory Manipulation

   _l_s

   "ls" (for list) lists the name of some or all  of  the  files  in
   your current directory. Thus, the command:

                            % ls

   will list all of the files in your current directory. The "ls"
   command can be used with wildcard characters to  display  certain
   categories  of  files within your current directory. For example,
   the command:

                           %ls *.bak

   will cause all the backup files to be displayed. If  you want  to
   display  the  files in some directory other than your current one
   it is necessary to specify the complete pathname  of  the  direc-
   tory. The following command illustrates this:

                        % ls /usr/tml/MP119

   _l_s -_l

   "ls -l" is similar to the "ls" command, but it gives more  infor-
   mation  about each file.  It includes the size (in bytes or char-
   acters), owner, modification date, protection information on each
   file  and  the number of links to the file. (If one also wants to
   know how many blocks the file occupies on the disk it  is  neces-
   sary to type the command "ls -s".)

   _m_v

   "mv" (for move) changes the name of a file in your directory.  If
   the  new  filename already exists, it will be deleted. The format
   of the command is as follows:

                  % mv <old filename> <new filename>

   _c_p

   "cp" (for copy) makes a duplicate copy of a file with a new name.
   After  giving  a  copy command you will have two files, identical
   except for their names. The format of the cp command is identical
   to that of the mv command.




                                - 30 -







                                  TUG

   _r_m

   "rm" (for remove) removes a file from  your  directory.   Once  a
   file is deleted it is gone forever, so be certain you really want
   to delete a file before you perform a delete command. If you  are
   going  to  delete  several  files simultaneously using a wildcard
   character (for example, "rm *.bak") the system will prompt you to
   confirm your intentions (by typing in "y" for yes).

   _c_a_t

   "cat" (for concatenate) allows you to concatenate the contents of
   specified  files.  For  example,  the following command will con-
   catenate the contents of "junka" and "junkb" and  display  it  on
   the screen:

                       % cat junka junkb

   The result of a concatenation can be placed in  another  file  by
   using the redirection convention (i.e.cat junka junkb > junkc).

   The cat command can also be used to display  the  contents  of  a
   file. This is accomplished by the using the command with only one
   argument - i.e. the name of the file to be displayed.  For  exam-
   ple, the following command:

                            % cat junka

   will cause the contents of "junka" to appear on the screen  in  a
   rapidly scrolling-up motion.

   _b_r

   "br" (for browse) allows you to view a  specified  file  on  your
   terminal page by page. For example the command:

                            % br junk

   would type the file junk on your screen with a pause  after  each
   page of the file. The "br" command knows what type of terminal is
   being used and will cause special characters to be displayed in a
   way  suited to the terminal type. For example, understriking will
   be displayed as reverse video on CRTs but as underlining  on  the
   line printer.









                                - 31 -







                                  TUG

   The "br" command can also be used as a  pipe.   For  example  the
   command:

                          nroff junk|br

   will cause the file "junk" to be  formatted  (i.e."nroffed")  and
   then displayed on your CRT screen on a page by page basis.

   _d_i_f_f and _c_m_p

   The commands "cmp" and "diff" are two  different  ways  of  doing
   essentially  the  same  thing  -  locating differing lines in two
   files that are being compared.

   With the cmp command the system displays the position  number  of
   the  character  and  the  line  number  at  which  the difference
   occurred. The general form of the command is

                     % cmp <file1> <file2>

   If the two files are identical no response is made.

   The diff commands works in a somewhat  different  fashion.   This
   command,  which  has the same format as the cmp command, displays
   the differing lines in the two files as well as their  locations.
   The response the command generates looks as follows:

             2c2
             < in which diff works.
             ---
             > in which diff tends to work.

   (Note: in the line identifier construct the number(s) to the left
   of  the  c  indicates  the  differing  line(s)  in  file1 and the
   number(s) to the right of the c indicates the  differing  line(s)
   in  file2.  The 2c2 resembles a Text Editor command that could be
   used to regenerate file2 from file1.)

   _c_h_m_o_d

   "chmod" (for change mode) changes the protection of a  file.   It
   takes  an  octal  protection  mode  (see  below)  and  a  list of
   filenames or directories and sets the desired privileges on them.
   There  are  three  categories  of protection mode applying to the
   three categories of usage - owner, group and all users. The octal
   code  for  setting  privileges  within the three categories is as
   follows:

             _M_o_d_e          _M_e_a_n_i_n_g

             400          Readable by owner
             200          Writable by owner

                                - 32 -







                                  TUG

             100          Executable by owner
              40          Readable by owner's group
              20          Writable by owner's group
              10          Executable by owner's group
               4          Readable by all users
               2          Writable by all users
               1          Executable by all users

   The three octal digits are used to set user  privileges  for  all
   categories  of user. For example, the default protection mode for
   non-executable  files  is  640.  This  assigns  read  and   write
   privileges to the owner, read privileges to the owner's group and
   no privileges to the general user. The corresponding default pro-
   tection mode for executable files is 750.

   _l_n

   "ln" (for link) is used to create a new filename for an  existing
   file.  That is, after the ln command has been performed, the file
   will have two names.  Going back  to  the  library  analogy  used
   above, the ln command would be analogous to writing a second name
   on a book.  Deleting a file is analagous to erasing the name from
   the binder of a book in the library, and if all of the names have
   been erased, then the book (file) is discarded. The format of the
   ln command is quite straightforward:

                % ln <old filename> <new filename>

   For example the command "ln circus mycircus" would allow  you  to
   reference  the  file  circus  using the filename mycircus.  ln is
   most commonly used to  reduce  typing  when  referencing  another
   users  file.   If  I  was an avid player of the game "hangman", I
   might tire of typing the name  "/usr/games/hangman"  everytime  I
   wanted  to run the program, so I might use the ln command to link
   the file with the name "hang" in my directory.

   _o_p_r

   "opr"  queues  files  to  be  printed  on  your   system's   line
   printer(s). The general form of the opr command is as follows:

   opr  [-ncopies]  [-iindentation]  [-Cclassification]  [-crb]   [-
   pprinter] [filename(s).....]

   As an example of how the opr command works consider  the  follow-
   ing:

             opr -3 -i10 -Csupersecret -p1  job1 job2

   This command will send to the printer three copies of  the  files
   job1  and  job2  with an indent of 10, a classification of super-
   secret, and with the job being sent to remote printer 1.

                                - 33 -







                                  TUG

   Note:  There are three other arguments to the opr command (-c  -r
          -b)  which  are  of  a somewhat specialized nature. For an
          explanation  of  their  use  see  OPR,  PRINT(I)  in   the
          "PWB/UNIX User's Manual."

   _l_p_q

   "lpq" (for line printer queue) causes a list of jobs in the  line
   printer  queue  to  be  displayed  on  the  screen. The list will
   include the job number(a star following the job number  indicates
   that  it  is  in the process of being printed), the login name of
   the person who submitted the job, the number of bytes in the  job
   and  the  identifier  of  the  printer  on  which the job will be
   printed.  The order of the jobs on the queue list is the order in
   which  they will be printed. The lpq command can be used with two
   arguments by the general user. -r is used with lpq  for  removing
   jobs  from the line printer queue. -r used with a job number will
   cause that job to be removed. If the job number  is  omitted  all
   the  user's  own  jobs in the queue will be removed.  If a job is
   already being printed -r will have no effect upon it.  To abort a
   job  that  is  in the process of being printed it is necessary to
   use lpq with the -k argument. (Use -k for printer0  and  -k1  for
   printer1.) Both -r and -x can be used by the general user only to
   terminate jobs which he himself owns.

   _c_h_d_i_r or _c_d

   "chdir" or "cd"  (for  change  directory)  changes  the  "working
   directory" of the user. In the library analogy (II.5) chdir would
   be analogous to a user walking over to another stack and  sitting
   down.   After the move, any book (file) names used would refer to
   the new stack (directory) the user  is  associated  with.   Chdir
   with no argument will change the directory to $s (i.e. your login
   directory or whatever directory you have defined as  you  default
   directory).  If you want to move to a directory that is contained
   within or was created within the current directory  you  can  use
   chdir  with  the  name of the directory only.  Otherwise you must
   specify the full pathname of the directory to which you are  mov-
   ing.  For  example,  if the current directory is /usr/tml and tug
   was created within this directory you can move to tug  by  simply
   typing  "chdir  tug". If, on the other hand you want to move from
   /usr/tml/tug to cprograms,  a  directory  that  was  not  created
   within /usr/tml/tug, you must type "chdir /usr/tml/cprograms".










                                - 34 -







                                  TUG

   _m_k_d_i_r

   This is a UNIX command which makes a subdirectory in the  current
   working directory. For example,

                         mkdir pplfiles

   makes a directory called pplfiles.

   _r_m_d_i_r

   When a directory is empty it may be deleted by this UNIX command.
   For example,

                         rmdir pplfiles

   deletes the directory "pplfiles".

   3.7.4.  Miscellaneous

   _q_o_t_d

   "qotd" (for quote of the day) types some  timely  quotation  from
   one of a variety of questionable sources. You will get a quote of
   the day, without even asking, when you log in for the first  time
   each  day.  If  one inane saying a day is not enough for you type
   "cookie" to get as many as your heart desires.  Often,  you  will
   get  an "on this day in history" type saying along with the quote
   of the day. You can specifically request this by typing "today".

   _n_e_w_s

   "news" provides the user with information concerning  the  latest
   developments on the system. The command without any argument will
   cause a  list  of  topics  on  which  news  is  available  to  be
   displayed. The command with a topic as an argument will cause the
   news on that topic to be presented.

   3.8.  Inter-User Communications


   _w_r_i_t_e

   "write" couples two terminals together so that the users can type
   to  each  other.  For example, if you want to ask a question of a
   fellow user and you know that he is logged on,  you  can  contact
   him  using  the write command. The write program is quite easy to
   use. The command "write" with the login name of  the  person  you
   are  trying  to contact will establish contact. The person at the
   other end of the line will receive the following message:

               Message from tml on tty p at ELROND

                                - 35 -







                                  TUG

                  To respond, type write tml

   The person sending the message should wait for some response from
   the  person  he's trying to contact before keying in his message.
   The person who has been contacted must make a connection by  typ-
   ing  in  "write".  He can then acknowledge the attempt to contact
   him by either typing in a response which will immediately  appear
   on the the other user's screen, or by hitting CTRL-Y. CTRL-Y will
   cause the message "Go ahead <login name>" to be displayed on both
   users' screens. To terminate a write session both users must type
   CTRL-D, which signals an end of transmission to the other user by
   causing  the  message  "<login  name>  has quit" to appear on the
   screen. The write program, with a slight variation, can  be  used
   to  contact  other users across the net. The following command is
   used to establish contact with a user on a different system:

             write <login name> at <host computer name>

   If you want to contact any one of several users with  the  telnet
   version  of  the  write  program  type  the user ids separated by
   blanks and enclose the entire  string  in  double  quotes.  Write
   will search for the users in the order typed and connect with the
   first one available.

   _m_e_s_g

   The mesg command is used to deny other  users  the  privilege  of
   sending  you  messages via the write command. The general form of
   the mesg command is as follows:

                        mesg [ n ] [ y ]

   Mesg with argument n forbids  messages  via  write  by   revoking
   non-user  write  permission  on the user's typewriter.  Mesg with
   argument y reinstates permission.  All by itself,  mesg  reverses
   the  current  permission.   In  all  cases  the previous state is
   reported.

   _s_n_d_m_s_g

   The sndmsg command is used for sending  mail  messages  to  other
   users.  After  typing in sndmsg the user will be prompted for the
   recipient(s) of the message, its subject  and the  message  text.
   The following is a sample of sndmsg prompts and user responses:









                                - 36 -







                                  TUG

   _______________________________________________________________
   |% sndmsg                                                      |
   |To: tml                                                       |
   |cc: ldn                                                       |
   |Subject: nothing                                              |
   |Type message, end with <EOT> (ctrl-D)                         |
   |This is some sample text used for purposes of illustration.   |
   |______________________________________________________________|

   After the message text has been typed in the system  prompts  the
   user  with a list of message processing alternatives. This prompt
   looks as follows:

   queue, send, editor (or re), ed, input, file,  justify,  display,
   or ?: queue

   The queue  and  send  commands  will  cause  the  message  to  be
   dispatched  without  any  intervening  processing. For local mail
   send and queue have the same effect. There is a difference,  how-
   ever, for mail being sent over the net. The send command will not
   return you to the shell level until the net connection  has  been
   made  and  all  messages dispatched. The queue command queues the
   message for net mailing and immediately returns you to the  shell
   level. There is one other way in which the use of sndmsg over the
   net differs from its usage on a local basis.   For  network  mail
   the  recipient  of  the  message  must  be identified by his host
   computer's name as well as by his login  name.  The  user  should
   respond to the "To:" prompt as follows for network mail:

                        To: tml@elrond

   For a consideration of the other processing options  it  is  sug-
   gested that the user consult the SNDMSG(I) entry in the "PWB/UNIX
   User's Manual".

   _m_s_g

   The msg command is used to read mail messages that have been sent
   to  you  via  the  sndmsg command. A user is notified that he has
   mail in two ways. If you are logged in and  not  using  the  RAND
   Editor  a  message  of the following type will appear on your CRT
   screen:

   ______________________________________________________________
   |                                                             |
   |              <bell> [You have mail] <bell>                  |
   |                                                             |
   |_____________________________________________________________|





                                - 37 -







                                  TUG

   If you were not logged on or were using the RAND  Editor  when  a
   message was sent, you will recieve the following message the next
   time that you log on:

                            You have mail

   Once informed that you have mail you can go about reading  it  by
   first typing "msg". This will cause the queue of messages in your
   mail file to be displayed. The display will resemble the  follow-
   ing:

   ______________________________________________________________
   |% msg                                                        |
   |Readmail -- version 2.3 of 3/2/79                            |
   |  1    160 char  1 Feb 1980 elrond at ELROND"password change"|
   |  2   7644 char 19 Feb 1980 Dlm at ELROND   [MP-220 file]    |
   |  3    118 char 25 Feb 1980 To: tml         nothing          |
   |  4    142 char 25 Feb 1980 To: tml         nothing          |
   |  5    233 char 25 Feb 1980 To: tml at elro Test             |
   |  6    233 char 25 Feb 1980 To: tml at elro test             |
   |6 messages                                                   |
   |For help type ?                                              |
   |-> ?                                                         |
   |_____________________________________________________________|

   Typing a question mark after the arrow  for  help,  as  is  shown
   above,  will  cause  a list of commands that can be used with the
   msg program to be displayed. The following represents a selection
   of these commands:

   ______________________________________________________________
   |Commands are:                                                |
   |d[elete] <message no>...                                     |
   |e[xit and overwrite current mail file to reflect deletions]  |
   |h[eaders of messages:] <message no>...                       |
   |n[ext-message-is:]                                           |
   |s[ave mail and exit]                                         |
   |t[ype] <message no>...                                       |
   |q[uit]                                                       |
   |_____________________________________________________________|

   The commands are more or  less  self-explanatory.  "delete"  will
   cause  the  specified  message  to be deleted from the mail file.
   "type" will cause the the message to be displayed on the  screen.
   "quit" will cause you to exit the msg program without any changes
   being made in the mail file. "exit" will cause you  to  exit  the
   program  with  the  mail  file  being  overwritten to reflect any
   changes. Save, on the other hand, will cause the  program  to  be
   exited  with the contents of the mail file being removed from the
   mail file and transferred to a file  called  "savemail".   For  a
   description of the other commands that are used with the msg pro-
   gram see the entry MSG(I) in the "UNIX Programmer's Manual."

                                - 38 -







                                  TUG

   Note: It is only necessary to type the first letter  of  each  of
         the commands used with "msg".

   3.9.  Languages


   UNIX supports a number of general purpose  programming  languages
   as  well  as several "language-like" text editors and macro pack-
   ages. The languages that are supported by UNIX will be  discussed
   in more detail in the section 4. At this point it will suffice to
   merely list the languages:

             fortran          ppl               basic
             f4p              as                pascal
             fc               cc                rc
             lisp

   3.10.  Logout and Login


   _L_o_g_o_u_t

   There are several ways of exiting from the shell (at its  topmost
   level  -  i.e. when you are working with a prompt). One way is to
   simply type in "logout". This method of exiting can  cause  prob-
   lems  in  some circumstances because it will cause all background
   jobs to be killed  (See  the  note  on  background  jobs  below.)
   "detach"  is  an  alternative  method  of  exiting the shell that
   leaves background jobs unaffected.  Finally,  exiting  the  shell
   can  be accomplished by keying in a CTRL-d.  CTRL-d, like logout,
   will cause background jobs to be killed.

   Note:  A process can be caused to run in background by  following
          the command which initiates the process with the character
          "&".  The process is said to run in background because the
          shell  doesn't wait for the process to be completed before
          accepting more commands but returns to a "state of  readi-
          ness"  while the process is still running.

          Detaching or logging out will "blitz" your  terminal.  Any
          output  that  a  background job might want to write to the
          terminal will be lost. This is to prevent output from  one
          user's  background job from annoying the user who succeeds
          him at the terminal. Also, it should be noted that network
          connections are terminated by a logout.

   _L_o_g_i_n

   The login command is used to change  from  one  user  account  to
   another. Using this command



                                - 39 -







                                  TUG

   simply involves typing in "login". This will cause the system  to
   prompt you for your login name and password. Like "detach," login
   will not kill any jobs that are running in background.

   3.11.  Peripheral Devices


   UNIX offers a wide variety of programs for using peripheral  dev-
   ices  in  file  transfers. Both UNIX-to-UNIX and certain UNIX-to-
   NON-UNIX transfers can be accommodated.  Several  auxiliary  pro-
   grams  are  available to allow exclusive use of a peripheral dev-
   ice.


   3.11.1.  Assigning and De-assigning Peripheral Devices

   Before using a peripheral device it is wise (i.e. required)  that
   it be "assigned" for your use.

   _A_s_s_i_g_n(_a_s_s:)

   Assign(ass) allows a user to obtain a  peripheral  device   dedi-
   cated for  his exclusive use.  The argument(s) specify each peri-
   pheral which the user wishes to reserve. The command used without
   any  arguments will display a table that lists the available dev-
   ices by ID and indicates the user (if  any)  to  which  they  are
   currently dedicated. The table will resemble the following:

   _______________________________________________________________
   |                 D E V I C E     T A B L E                    |
   |      Device  Owner                        Comments           |
   |      ------  ----- ------------------------------------------|
   |1.    tap0          /*                                      */|
   |2.    mt1           /*                                      */|
   |3.    ht0     tml   /*                                      */|
   |4.    rk0     mtl   /*                                      */|
   |5.    cat     dlm   /*   Graphic Systems C/A/T typesetter   */|
   |6.    nmt0          /*   no rewind mt0                      */|
   |7.    nht0          /*   no rewind ht0                      */|
   |______________________________________________________________|

   The device IDs signify the following: tap refers to  DECtape;  mt
   indicates mag tape; ht refers to high density mag tape(1600 bpi);
   rk indicates cartridge disk; cat  specifies  the  phototypsetter;
   and nmt and nht refer to non-rewindable mag tape and high density
   mag tape respectively.







                                - 40 -







                                  TUG

   _D_e_a_s_s_i_g_n(_d_e_a_s)

   The deassign(deas) command is used to release peripheral  devices
   that  have been assigned to a particular user via the assign com-
   mand.  The command used with a device  ID  as  an  argument  will
   cause  that  particular  device only to be released (provided, of
   course, that the device is assigned to  the  user).  The  command
   used without any arguments will cause all the devices assigned to
   the user to be released. The commands used for exiting the  shell
   (i.e.logout  and CTRL-d) will also cause all the devices assigned
   to the user to be released.

   3.11.2.  Common Programs for Peripheral Use

   _t_p

   tp is used to copy UNIX files from disk to tape (DECtape  or  mag
   tape)  and  vice-versa.  The general form of the tp command is as
   follows:

                          tp [key] [name...]

   The key consists of any of several functions and function  modif-
   iers  (indicated by letters and digits) that control the specific
   peripheral device. "Name" in the above command refers to the file
   or directory names which are to be operated upon by tp. What fol-
   lows is a list of  tp  commands  for  popular  peripheral  device
   applications:

   tp tvm0        This command will cause a copy of a  tape's  table
                  of  contents  to  be  sent to the standard output.
                  Before transferring files from tape to  disk  it's
                  good to know what's on the tape so that you can be
                  selective with regard to what will be transferred.

   tp crvm0       This command writes files on mag  tape.  Since  no
                  file name is specified the current directory(.) is
                  assumed by default. All  files  that  are  in  the
                  current  directory  and  all files that are in any
                  directories in the current directory will be writ-
                  ten on the tape.

   tp crvm0 hold  This command wil cause the file or directory named
                  "hold" to be written on mag tape.

   tp xvm0        This command will cause all files that  are  on  a
                  mag  tape  to  be  written  on  disk, creating any
                  necessary files or directories in the process.





                                - 41 -







                                  TUG

   Note: File and directory names used with the tp command  must  be
         specified  exactly.  tp  will  not  recognize  as identical
         filenames which  are  logically  the  same  in  UNIX  (i.e.
         "./abc" and "/usr/dmr/abc").

   _t_a_r

   tar is a Seventh Edition UNIX peripheral  program  which  closely
   resembles  tp.  It  should  be  noted, however, that tar offers a
   number of advantages over tp. In a general vein, tar works effec-
   tively  with  long pathnames and a large number of files, both of
   which can cause problems for tp. Also,  tar  is  more  compatible
   with the full range of UNIX systems. In a more specific vein, tar
   offers a number of function modifiers that are not available with
   tp.  For a full listing of functions and modifiers see the tar(I)
   listing in "UNIX Programmer's Manual, Seventh Edition."

   _f_i_l_e_x

   The filex program closely  resembles  tp.  The  major  difference
   between the two is that filex can read and write DOS-11 formatted
   DECtapes and magtapes whereas tp works  in  an  exclusively  UNIX
   environment.  The  general format of the filex command is as fol-
   lows:

                       filex key [file....]

   The keys used with the command are for the most part the same  as
   those  used  with  tp.  (For  a  full listing of the requests and
   modifiers constituting the key see the Filex(VI) listing  in  the
   "PWB/UNIX  User's  Manual.")  As  an example of the filex command
   consider the following:

                       filex rvm0 hold.txt

   This command will cause the UNIX-formatted file "hold.txt" to  be
   written on magtape in DOS-11 format.  Note that the DOS file nam-
   ing conventions are used.

   _r_t_p_i_p

   The rtpip program closely resembles filex. The essential  differ-
   ence  between  the two is that rtpip can read and write DEC RT-11
   formatted DECtapes and RK05 cartridges, whereas, as noted  above,
   filex  works  with  DEC  DOS-11  tapes. The general format of the
   rtpip command is as follows:

                       rtpip key [file....]

   The key is composed of two characters: one specifies the function
   to  be  performed and the other identifies the RT-11 device to be
   accessed. The two most important function key  characters  are  r

                                - 42 -







                                  TUG

   and  x: r copies files _t_o the RT-11 device and x copies them _f_r_o_m
   the RT-11 device (currently DECtape or RK05  cartridge).   As  an
   example of the rtpip command consider the following:

                         rtpip r0 junk

   This will cause the UNIX file junk to be copied to RT-11 device 0
   (DECtape).  As  a  result a copy of junk will be transferred from
   disk to the file 'JUNK.   ' which is on tape in  RT-11  directory
   format.  If  no  file by the given name exits it will be created,
   otherwise an existing file of that name will be over-written. For
   more  information  on the rtpip command see the entry RTPIP(I) in
   the "PWB/UNIX User's Manual."

   _d_d

   dd is a program designed for copying and converting a  file  from
   "foreign"  (i.e.  non-UNIX) format to UNIX format and vice-versa.
   The general form of the dd command is as follows:

                     dd [option=value].....

   The option-value combination refers to such things as  the  input
   block size, filename and character set (to be converted).  (For a
   fuller description of the options and values see the entry  DD(I)
   in the "PWB/UNIX User's Manual".) In its most popular application
   dd is used to copy tapes originating on non-UNIX systems to  UNIX
   format. For example, suppose you wanted to convert to UNIX format
   a tape that is in a popular IBM format - EBCDIC tape blocked  ten
   80-byte  card  images  per record. The command used to accomplish
   this appears as follows:

      dd   if=/dev/rmt0  of=x  ibs=800  cbs=80  conv=ascii,lcase

   The first option-value combination specifies the input  filename.
   This is actually the descriptor of the physical device upon which
   the tape to be converted is mounted. The second option-value com-
   bination  specifies  the output filename. The file that is copied
   from the tape will be called "x". The third combination indicates
   the  input  block size in bytes. For our IBM tape a block size of
   ten 80-byte card images constitutes an 800 byte input block size.
   The  fourth  option-value  combination  specifies  the conversion
   buffer size. The conversion buffer is used when acsii  or  ebcdic
   conversion  is  required.  In the case being considered 80 ebcdic
   characters are read into the conversion buffer, are converted  to
   ASCII,  any  trailing  blanks are removed, a newline character is
   added, and the line is then sent to output. The process continues
   until the end of file is reached. The final option-value combina-
   tion indicates the type of  conversion  that  is  to  take  place
   between  input  and output. In response to the command being con-
   sidered ebcdic character will be converted  to  ascii  and  upper
   case characters to lower case ones.

                                - 43 -







                                  TUG


   For more information on dd see the entry "DD(I)" in the "PWB/UNIX
   User's Manual".

   _c_p_i_o

   cpio is a program which copies files from disk to tape and  vice-
   versa.  The  command  assumes  three  different  forms  that vary
   according to the task to be accomplished:

   cpio -o   This command takes a list of pathnames from  the  stan-
             dard  input  and copies the files and associated status
             information  onto   the   specified   output   (usually
             magtape).

   cpio -i   This command is the reverse of the  previous  one.   It
             will  return  to disk files that have been placed on an
             output medium (again, usually magtape) using  the  cpio
             -o command.

   cpio -p   This command combines the functions of cpio -o and cpio
             -i.  It  causes  files  to  be copied from the standard
             input to an output medium and back again  in  a  single
             operation.  The  files  being  moved  are assigned to a
             specified new directory, which  directory  is  in  turn
             assigned to the current directory.

   The three commands, in particular cpio -i and  cpio  -p,  have  a
   number  of  options.  These options accomplish such things as the
   creation of new directories where needed.  (For a full listing of
   the  options  see  the  entry  cpio(I)  in  the  "PWB/UNIX User's
   Manual.") As an example of how the  commands  work  consider  the
   following:

                  ls | cpio -o > /dev/mt0


                  chdir olddir
                  find . -print| cpio -pdl newdir

   The first of the above commands causes a listing of  the  current
   directory's contents to be piped to cpio -o which in turn directs
   the listed files to be written out onto magtape. In  effect,  the
   contents  of  the current directory are archived. The second com-
   mand is somewhat more complicated. find recursively descends  the
   directory  hierarchy from the pathname, in this case the pathname
   is that of the the current directory - olddir. The listing of the
   files  located  by find is piped to cpio which in turn causes the
   files to be copied out to the standard output and  then  returned
   as  the  contents  of the directory "newdir." The options d and l
   tell the system to create new directories  where  needed  and  to
   link  files  rather than copy them when possible.  The net effect

                                - 44 -







                                  TUG

   of the command is that a  copy  of  the  current  directory,  the
   directory  "olddir",  is  made  and  entered in the new directory
   ("newdir").

   For more information on cpio  see  the  entry  "CPIO(I)"  in  the
   "PWB/UNIX User's Manual".

   _m_t_i_o

   mtio is a program for analyzing,  copying  and  extracting  files
   from  "foreign"  (i.e.non-UNIX) magtapes. In the analyze mode the
   program tries to figure out what a foreign tape looks like - i.e.
   the  size of records, the number of records per file, the size of
   files, etc. As an example of the analyze mode of the program con-
   sider the following command:

                         mtio -tv /dev/rmt0

   This will cause a "verbose"(-v) table of contents(-t) of the  800
   bpi tape on drive 0 to be directed to the standard output.

   In the copy mode the program will copy  multiple  file  tapes  of
   varying  record  sizes  from  one device to another, changing the
   density of the tape in the process if so desired.  As an  example
   of the copy mode of the program consider the following command:

                    mtio -c /dev/rmt1 /dev/rht0

   This will cause the 1600 bpi tape on drive 0   to  be  copied(-c)
   onto the 800 bpi tape on device 1.

   Extraction is the final mode of operation available with the mtio
   program.  In  the  extract mode, which presumes that you know how
   the foreign tape is formatted, the program  will  transfer  files
   from  tape  to  disk  with an arbitrary character delimiter being
   inserted after each record if so desired. As an  example  of  the
   extract mode consider the following:

                     mtio -x junk /dev/rmt0

   This will cause all files on the tape mounted  on  drive  0  (800
   bpi)  to  be  extracted  onto  disk,  each  as  a  separate file,
   filenames being junkaa, junkab, etc.  For a full consideration of
   mtio see MTIO(I) in the "PWB/UNIX User's Manual(Supplement)."

   3.12.  Games


   UNIX offers several games.  However, they are not  available  for
   use  during working hours. To play a game type the following com-
   mand:


                                - 45 -







                                  TUG

                            % games

   The games program will check to see if it is okay to  play  games
   at  the current time. If it is, a list of available games will be
   displayed. To play the game of your choice you simply type in the
   name  of  the game (with any necessary arguments) and the it will
   begin.














































                                - 46 -







                                  TUG

   4.  Languages and Editors



   UNIX offers several software development tools,  several  popular
   language translators, and some esoteric language translators.  It
   also offers  a  variety  of  text  editors  and  debug  packages.
   Finally,  as  an  added  feature  UNIX  offers  a  set  of cross-
   assemblers  and  link-editors  for  the   most   popular   micro-
   processors.

   4.1.  C


   C is a systems programming language  developed  at  Bell  Labora-
   tories.  It is the preferred programming language on UNIX systems
   and indeed the UNIX operating system itself is written in C.  The
   UNIX  shell  command "cc" is used to invoke the C compiler.  Com-
   piled programs are executed via the a.out convention.  The compi-
   lation  process deposits an executable file called "a.out" in the
   user's current  directory.  Typing  this  filename  (i.e.  a.out)
   causes the program most recently compiled to begin executing.

   Documentation on the C programming language includes the  follow-
   ing:


       o+   "The C Programming Language" by Brian  W.  Kernighan  and
           Dennis   M.   Ritchie,  (Englewood  Cliffs,  New  Jersey:
           Prentice-Hall, Inc., 1978).

       o+   "UNIX Programming" by Brian W. Kernighan  and  Dennis  M.
           Ritchie  in "Documents for the PWB/UNIX Time-Sharing Sys-
           tem."

       o+   "C Reference Manual" by Dennis M. Ritchie  in  "Documents
           for the PWB/UNIX Time-Sharing System."

       o+   "Programming in C - A Tutorial" by Brian W. Kernighan  in
           "Documents for the PWB/UNIX Time-Sharing System."

       o+   "A New Input-Output Package"  by  Dennis  M.  Ritchie  in
           "Documents for the PWB/UNIX Time-Sharing System."

       o+   "A General-Purpose Subroutine  Library  for  PWB/UNIX  by
           Alan  L.  Glasser  in  "Documents  for the PWB/UNIX Time-
           Sharing System."

       o+   "Version 7 C Compiler," PIB-78-002.

       o+   "Information for C Programmers," PIB-78-003.


                                - 47 -







                                  TUG

   Note: The material covered in the papers "UNIX  Programming"  and
         "The  C  Reference Manual" is effectively covered in "The C
         Programming Language".

   4.2.  FORTRAN


   FORTRAN is one of the earliest of  the  "higher  level"  computer
   languages  to gain general acceptance.  It is available on a wide
   range of computers, and is still used today for a wide  range  of
   scientific  applications.   FORTRAN  is a compiler rather than an
   interpreter, which means that it takes the text of a program  and
   translates  it  into instructions which the computer understands.
   This requires that a program first be  entered  into  the  system
   using  a text editor, next the FORTRAN translator program is used
   to translate the file into an executable form,  and  finally  the
   resulting file is run.

   There are in fact three versions of FORTRAN  that  are  currently
   running on UNIX: fc (UNIX FORTRAN), fortran (RT-11 FORTRAN),  and
   f4p (FORTRAN IV PLUS). Some basic information concerning the  way
   in  which  programs  are  compiled  in  each  version  and  their
   strengths and weaknesses is presented below.

   4.2.1.  Fortran

   Fortran is adapted from the RT-11 version  of  the  standard  DEC
   FORTRAN. Fortran's biggest selling point is the fact that it con-
   forms to the DEC standard FORTRAN. Thus, FORTRAN programs written
   on  DEC  machines  not  running  UNIX  are easily transferable to
   machines running UNIX. On the liability side of the ledger,  for-
   tran  is not as efficient as FORTRAN IV PLUS.  The following com-
   mand will compile a FORTRAN program:

                  % fortran -no -st mainprogram

   This will cause the program named "mainprogram"  to  be  compiled
   with no object code being retained(-no) and a statistical summary
   being printed at the end of compilation. The command  presupposes
   that   the  code  for  "mainprogram"  resides  in  a  file  named
   "mainprogram.for".   The  object  will  be  left  in   the   file
   "mainprogram.obj".  A listing had it been asked for (using -nl:4)
   would be left as "mainprogram.lst".  One  must  then  "link"  the
   program with the runtime support and any other modules:

                         % link mainprogram -f4

   This will leave the executable code as "mainprogram.out" and  the
   load map (if requested) as "mainprogram.map".  The following com-
   mand will cause a compiled UNIX FORTRAN to execute:

                          % mainprogram.out

                                - 48 -







                                  TUG

   For a full list of the arguments that can be used with  the  for-
   tran  command see FORTRAN(I) in the "PWB/UNIX User's Manual." For
   more information on linking and executing  FORTRAN  programs  see
   LINK(I)  in  the  "PWB/UNIX User's Manual." (Note we use LINK and
   not LINKR or  LINKER!!)  An  in-depth  consideration  of  fortran
   itself  can be found in J. N. Rottman's "A Guide to the UNIX For-
   tran System" and the "PDP-11 FORTRAN Language Reference Manual."

   Note: Fortran requires a DEC Fortran license. Most  UNIX  systems
          at  the  Agency  do  not have this license and thus do not
          support Fortran.  To find out if your system does  support
          it consult your system administrator.

   4.2.2.  fc

   Just as fortran approximates a standard FORTRAN IV  for  all  DEC
   machines  so  fc  approximates ANSI standard FORTRAN for all UNIX
   systems at the Agency. fc's strongest point is  that  it  handles
   numerical  calculations more effectively than either UNIX FORTRAN
   or f4p. This is because it is not hampered by some  of  the  bugs
   that  plague  the other two versions. Another point in fc's favor
   is the fact that all UNIX systems at the agency  support  it.  On
   the  liability  side  of  the  ledger,  fc  falls short of f4p in
   overall efficiency, especially in floating point.  The  following
   command will cause an fc program to be compiled:

                       % fc mainprogram.f

   The command presupposes that the code for the program resides  in
   a  file  named "mainprogram.f". The fc command will leave an exe-
   cutable program named "a.out" in  the  user's  filespace.   (Note
   that  fc  does not use the filename.out convention of fortran and
   f4p.) To execute the program it is only necessary to  type  a.out
   and  input whatever data is necessary. For more information on fc
   it is suggested that the user  consult  FC(I)  in  the  "PWB/UNIX
   User's Manual."

   4.2.3.  f4p

   The final version of FORTRAN to be considered is f4p  or  FORTRAN
   IV PLUS. FORTRAN IV PLUS's biggest selling point is the fact that
   it is the most efficient of the versions of  FORTRAN  running  on
   UNIX. On the negative side, f4p is plagued by a certain number of
   bugs, some of which  limit  its  effectiveness  in  computations.
   Also, some might consider as a liability the fact that FORTRAN IV
   PLUS must be leased at a cost of $6,000. (If f4p is not available
   on your system and you are interested in obtaining it contact the
   UNIX Support Group.) The following command will cause an f4p pro-
   gram to be compiled:

                       % f4p mainprogram.f4p


                                - 49 -







                                  TUG

   The   command   will   leave   an   executable   program   called
   "mainprogram.out" in the user's current directory. Thus, the pro-
   gram is executed by typing  the  command  "mainprogram.out".  For
   more information on FORTRAN IV PLUS consult "PIB-78-005 : FORTRAN
   IV PLUS for UNIX" and the entry F4P(I) in  the  "PWB/UNIX  User's
   Manual."

   4.3.  BASIC


   BASIC is a language designed for time-sharing, which  means  that
   it  is interactive, with built in editing and debugging.  In gen-
   eral, a BASIC program will not run as fast as a FORTRAN  program,
   but  is often easier and quicker to get running.  To use BASIC on
   UNIX begin by typing "basic".  The interpreter will respond with:

                       unix basic version 4-a
                       ready

   At this point the user must type in the name of the file contain-
   ing  the  program  to be executed preceded by the word "old". For
   example:

                              old junk

   Though the postfix ".bas" must be part of the  filename  it  need
   not  be  included when the filename is being passed to the inter-
   preter. When the interpreter returns with "ready"  the  user  can
   begin  program  execution  by  typing  in  "run".  Any  syntax or
   input/output errors will be marked at this point.  To halt execu-
   tion  of  the  program and return to the command level one should
   follow the standard convention of hitting rubout.  To  return  to
   the  command  level  of the UNIX shell after the program has com-
   pleted execution the user should  respond  to  the  interpreter's
   "ready" prompt by typing in "sys".

   The following documents on the BASIC programming language  should
   be readily available:


       o+   BASIC(VI) in "PWB/UNIX User's Manual"(with  the  "Supple-
           ment to the PWB/UNIX User's Manual").

       o+   "BASIC-11  Language  Reference  Manual,"  (Maynard,  Mas-
           sachusetts: Digital Equipment Corporation, 1976).

       o+   "BASIC-11/RT-11 User's Guide,"  (Maynard,  Massachusetts:
           Digital Equipment Corporation, 1976).





                                - 50 -







                                  TUG

   4.4.  PASCAL


   Some of the UNIX systems at the Agency  now  support  Netherlands
   PASCAL. To compile PASCAL programs use a command of the following
   type:

                           pc junk.p

   PASCAL program filenames must end with a ".p".

   The compilation process creates a file called "e.out"  which  can
   be executed using a command of the following type:

                              em1

   The following documentation on PASCAL is currently available:


       o+   "UNIX Pascal-VU User's  Manual(TR-R53-01-80,  S-220,657)"
           by Linda N. Davis, Randall S. Hammel and C. Terrence Ire-
           land, (Department of Defense, Ft. George G. Meade, 1980).

       o+   "PASCAL-VU Reference Manual" by Johan W. Stevenson,  this
           document  is  on-line  on  some  UNIX  systems and can be
           accessed by the command "doc pc".

       o+   "PC(I)", this manual page can be found  on-line  on  some
           UNIX  systems.   It  can  be accessed by the command "man
           pc".

       o+   "PASCAL: User Manual and Report" by Kathleen  Jensen  and
           Niklaus  Wirth,  (New York Springer-Verlag, 1978), avail-
           able in the library and at most local college bookstores.

       o+   "PASCAL User's Guide" by Randy Hammel and Terry  Ireland,
           (currently in progress).

   4.5.  The Text Editors


   4.5.1.  ED: The UNIX Editor

   ED is the editor provided by Bell Labs with the UNIX system.   It
   is  a  line oriented editor with a thorough set of documentation.
   Text editing is accomplished through the use of a wide variety of
   commands  which  (at  least  remotely) resemble the statements of
   conventional programming languages. The UNIX editor  is  accessed
   by the the following command:

                          % ed <filename>


                                - 51 -







                                  TUG

   The number of characters in the file,  which  we  assume  exists,
   will  be  displayed  and  the  editing session can begin with the
   issuing of any editing command. A file can be created in the UNIX
   text editor by the following sequence of commands:

                            % ed
                            a
                            <text>
                            .
                            w junk
                            q

   The "a" command (for append) adds the text to what's in the edit-
   ing  buffer  (nothing  in this case). The "w" command then copies
   the contents of the buffer into a file  which  it  names  "junk".
   The  "q" command will cause you to exit the Editor.  This look at
   some of the editor commands is intended to do nothing  more  than
   convey  to  the reader something of the "flavor" of the UNIX Text
   Editor. For a more detailed consideration of the UNIX  Editor  it
   is suggested that the following documents be consulted:


       o+   "A Tutorial Introduction to  the  UNIX  Text  Editor"  by
           Brian  W.  Kernighan  in Documents for the PWB/UNIX Time-
           Sharing System."

       o+   "Advanced Editing on UNIX" by Brian W. Kernighan in Docu-
           ments for the PWB/UNIX Time-Sharing System."

   4.5.2.  qed

   Qed is a programmable text editor, intended primarily for use  by
   programmers. For practical purposes Qed is a superset of the UNIX
   Editor (Version 6). It is, however,  somewhat  more  complex  and
   difficult to use.  Thus, the average user is likely to find Qed's
   power unnecessary, even troublesome, and its use is  discouraged.
   For  the  "sophisticated" user who is willing to learn how to use
   it properly, however, Qed is a powerful tool, both when  used  as
   an editor and when used as a (rather idiosyncratic and low-level)
   programming language. The following document is available for use
   by those interested in tackling Qed:


       o+   "Programming  in  Qed:  A  Tutorial"  by   Robert   Pike,
           (included  as a supplement to "Documents for Use with the
           PWB/UNIX Time-Sharing System").







                                - 52 -







                                  TUG

   4.5.3.  The RAND Editor

   In contrast to the UNIX Editor, which is a line editor, the  RAND
   editor  is  a  page editor. What this means in practical terms is
   that the RAND Editor is designed for "cut and paste"  type  edit-
   ing.  What you see on the screen is what the file "looks like" on
   a page by page basis. Characters, lines  and  whole  portions  of
   text  may be deleted, separated by "white space" and moved about.
   In addition, the RAND Editor offers several interactive text pro-
   cessing  operations,  including justification, paragraph fill and
   word hyphenation.  Also, the RAND Editor permits user-defined and
   system-defined  text  processing programs to be accessed interac-
   tively from the editor.  The command language of the RAND  Editor
   is based upon function keys; so, in effect, the terminal keyboard
   provides a list of editor functions. To gain access to  the  RAND
   Editor type the following command:

                          % e <filename>

   If the file already exists its first  page  will  appear  on  the
   screen.   Subsequent  pages  can  be accessed by hitting the NEXT
   PAGE or SCROLL UP keys.  If the file does not  exist  the  editor
   will prompt you to create it by hitting the USE key after gaining
   access through the e command.  This superficial consideration  of
   the  RAND  Editor should be followed up with a more detailed con-
   sideration. For this it is suggested that the reader consult  the
   following documents:


       o+   "The CRT Text Editor NED  -  Introduction  and  Reference
           Manual"  by  Walter  Bifosky, (Santa Monica, CA: The RAND
           Corporation , 1977).

       o+   "RAND Editor" in "MP-119:  Introduction  to  UNIX"  (This
           document  is intended for the beginner and/or unsophisti-
           cated user).

       o+   "E(I) in "PWB/UNIX User's Manual."

   4.5.4.  teco

   TECO is a character oriented  editor  developed  by  the  Digital
   Equipment  Corporation.  One  character on a line may be modified
   without affecting the rest of  the  line.   TECO's  structure  is
   basically this:

          Input File------->Editing Buffer------->Output File

   The files which TECO modifies consist of  a  sequence of "pages".
   A page consists of a sequence of lines, and a line, of course, is
   a sequence of characters.  TECO starts by   reading   the   first
   page   of   the  input  file  into  the  buffer, where the actual

                                - 53 -







                                  TUG

   editing is done.  Associated with the   buffer  is  a  "pointer",
   indicated by a dot, "." .  The pointer always  sits  BETWEEN  two
   characters. Once the pointer is positioned, deletions and  inser-
   tions  are  easily made  before  and  after  the pointer, and the
   surrounding lines can be displayed without  moving  the  pointer.
   The command for entering TECO is as follows:

                          % teco <filename)

   This presumes that the file to be edited exists. A  file  can  be
   created in TECO by using the following sequence of commands:

                          % teco
                          ew <filename> $$
                          <lines of text>
                          ex $$

   (Note: the "$" does not refer to the character "$" but represents
   <esc>.)

   When editing on the page is completed, it can be  passed  to  the
   output file and the next one read in by entering the "p" command.
   An exit command, "ex", finalizes all changes and leaves the  user
   with  a  new, edited copy of the file. What has been presented in
   the way of a description of TECO is, of  course,  the  bare-bones
   minimum.   For  more details it is suggested that the reader con-
   sult the following documents:


       o+   "Introduction to TECO (Text  Editor  and  Corrector)"  in
           "DECSYSTEM10  User's  Handbook",  (Maynard,  MA:  Digital
           Equipment Corporation,1972).

       o+   "An Introduction to TECO," (a PIB in the making)

   4.6.  The Debugging Programs

   Debugging tools generally provide a wealth of  information  about
   the  inner  workings  of  programs.  These tools are available on
   UNIX to allow users to examine  "core"  files  that  result  from
   aborted   programs.   Some  of  the  debugging  programs  provide
   enhanced capabilities to examine "core" and other  program  files
   in  a variety of formats, run programs with embedded breakpoints,
   and patch files.

   4.6.1.  DB

   This program is the "original" debugger provided with  UNIX.   It
   can examine "core" files and patch (change) binary files prior to
   execution.



                                - 54 -







                                  TUG

   4.6.2.  CDB

   The C debugger is designed to work best with C programs.  It  can
   give  subroutine/function  calling  sequences, knows about C pro-
   grams and how they run, and can execute and trace the running  of
   a  C  program.   Breakpoints are used to allow a person to stop a
   program and allow an examination of  the  various  variables  and
   registers used by the program.

   4.6.3.  DDT

   This is a program from Monterey and is _n_o_t the Harvard  DDT.   It
   is similar in capabilities to CDB but harder in some ways to use.
   However some of the gurus seem to like it.

   4.6.4.  ADB

   This is the newest and best from Bell Laboratories.  It  has  all
   of  the  good features of the above debuggers and more.  It knows
   about the run-time implementation of all the popular languages as
   well as esoteric languages like ALGOL 68.

   4.6.5.  References

   As should be obvious, the above documentation offers little  help
   in  the  way  of  actually using the debuggers. For assistance in
   this regard it is suggested that the user consult  the  following
   documents:


       o+   "A Tutorial Introduction to ADB" by J. F.  Maranzano  and
           S.R.  Bourne, (included as a supplement in "Documents for
           Use with the PWB/UNIX Time-Sharing System" and  in  "UNIX
           Time-Sharing  System:  UNIX  Programmer's Manual, Seventh
           Edition").

       o+   "ADB(I)" in "PWB/UNIX User's Manual."

       o+   "DDT(I)" in "PWB/UNIX User's Manual."

       o+   "CDB(I)" in "PWB/UNIX User's Manual."

       o+   "DB(I)" in "PWB/UNIX User's Manual."










                                - 55 -







                                  TUG

   4.7.  Assemblers


   4.7.1.  AS

   The UNIX/PDP-11 assembler "as" is a conventional two-pass  assem-
   bler  without  macro  capabilities.  To call the UNIX assembler a
   command of the following general form is used:

                  as [-] file1, file2.....filen

   If several filenames are specified in the argument list they will
   be  concatenated and assembled together.  The output of an error-
   free assembler run is placed in an executable file named "a.out".
   The  output  of  several assembler runs can be combined with each
   other and with library routines by using the  link  editor  "ld".
   The  argument "-" will cause all undefined symbols in the current
   assembly to be made undefined external.  For more information  on
   "as"  it  is  suggested that the user consult the following docu-
   ments:


       o+   "AS(I)" in "PWB/UNIX User's Manual".

       o+   "UNIX Assembler Reference Manual" by Dennis M. Ritchie in
           "Documents for the PWB/UNIX Time-Sharing System".

   4.7.2.  MACRO

   Macro is the UNIX version of DEC Macro-11.  The  MACRO  Assembler
   assembles  one  or  more source files containing MACRO statements
   and produces output consisting of  a  relocatable  binary  object
   file  and an assembly listing followed by a symbol table listing.
   To call the MACRO Assembler a command of  the  following  general
   form is used:

        macro [option1 option2....] file1 file2........filen

        linkr [option1 ... ] filen

   If several filenames are specified in the argument list they will
   be  concatenated and assembled together.  The output of an error-
   free  assembler  run  is  placed  in  an  executable  file  named
   "filen.obj",  where  filen  is the last file in the argument list
   unless otherwise  specified.  The  object  file  must  be  passed
   through  the  link-editor  "linkr" to create an executable output
   file named "filen.out".  (link and  linker  are  also  acceptable
   link-editors.)  The  output of several assembler runs can be com-
   bined with each other and with library routines by using the link
   editor.   The  program "libr" is used to make and maintain object
   libraries.  Users are cautioned that the object output from MACRO
   (and  RT-11  fortran and F4P) are not compatible with output from

                                - 56 -







                                  TUG

   the UNIX assembler "as" and the C compiler.  A  program  CONV  is
   used to convert. For more information on the UNIX MACRO Assembler
   and related topics it is suggested that the user consult the fol-
   lowing documents:


       o+   "Introduction to the MACRO Assembler" in  the  "DOS/BATCH
           Handbook,"  (Maynard, MA: Digital Equipment Corporation ,
           1974).

       o+   "MACRO(I)" in the "UNIX Programmer's Manual."

       o+   "LINKR(I)" in the "UNIX Programmer's Manual."

       o+   "LIBR(I)" in the "UNIX Programmer's Manual."

   Note: "MACRO(I)" specifies the ways in the UNIX  MACRO  Assembler
          differs from DEC MACRO-11. For a full consideration of the
          MACRO Assembler one must go to the DEC document.

   4.8.  TRANS


   Trans will translate DOS assembly language input (standard  input
   is  the  default) into UNIX assembly language and write it out to
   the standard output. As an example of the trans command  consider
   the following:

                  trans dosfile > unixfile

   This will cause the DOS assembly language in the  file  "dosfile"
   to  be  converted  into UNIX assembly language and written in the
   file "unixfile".

   The trans program should be used with caution because  there  are
   problems associated with it. In particular, constructions that do
   not exist under  UNIX  assembly,  for  example  MACROS,  will  be
   translated but they will be meaningless. It is best to read up on
   both types of assembly langauges so as to be able  to  check  the
   adequacy of the translation made by trans.

   4.9.  lisp


   A version of the lisp interpreter is available  on  some  of  the
   Agency's  UNIX systems. It is ULISP V1.2 (ULISP for PDP-11's with
   Memory Management), which was developed by Robert  L.   Kirby  of
   the  University  of  Maryland  Computer  Science Center. ULISP is
   accessed from the UNIX shell by typing the




                                - 57 -







                                  TUG

   the command "lisp". Any description of how ULISP works is clearly
   beyond  the scope of this terminal user's guide.  For information
   on this somewhat esoteric topic it is suggested that  the  reader
   consult the following documents:


       o+   "ULISP for PDP-11s with Memory Management" by  Robert  L.
           Kirby,  (TR-546; MCS-76-23763; Technical Report, Computer
           Science Center, University of Maryland, College Park, MD,
           1977).  This  document  is  available  on-line. It can be
           accessed by typing "doc lisp".

       o+   "LISP 1.5 Primer" by C. Weissman, Dickensen, Inc., 1967.

   Note: The first reference presupposes familiarity  with  LISP  in
         general so it is essential that the reader who is not fami-
         liar with LISP consult a work of the  type  represented  by
         the second reference.

   4.10.  PPL


   PPL (Polymorphic Programming Language) is a language developed at
   Harvard  for  instructional  use.   It  is  a  highly interactive
   language with great flexibility.  Currently, PPL is not available
   on the Agency's UNIX systems.  If you are interested in having it
   installed on your system contact  your  system  administrator  or
   UNIX Software Support.  If you would like to learn more about PPL
   it is suggested that you consult the following documents:


       o+   "An Introduction to PPL Programming" by T.A.  Standish.

       o+   "PPL Users Manual" by T.A.Standish and E.A.  Taft

   4.11.  Cross-Assemblers (*)

   The R812 Microprocessor Techniques Lab  has  made  available,  on
   UNIX,  cross  assemblers  and linking loaders for the 8080, 9900,
   Z80, 6800, 6809 and 8086 microprocessors. The  cross  assemblers,
   which  are written in FORTRAN IV, translate symbolic machine code
   into physical machine code.

   The user interested in using the cross assemblers on UNIX  should
   consult the following documents:


       o+   "Microprocessor Relocatable Cross  Assemblers"  by  Nancy
           Marks and Tony Procopio, PIB-79-01.

       o+   "XASM(VI)" in "PWB/UNIX User's Manual".


                                - 58 -







                                  TUG

       o+   "XLNK(VI)" in "PWB/UNIX User's Manual".




















































                                - 59 -







                                  TUG

   5.  Appendix A: Terminal Session



   What follows is an example of a  terminal  session  which  illus-
   trates how you login, create an f4p file, compile it, execute it,
   edit errors, and finally re-execute it.

   Elrond -- Unix 6th Ed.
   login: tml
   password:
   For latest system news as of 6 Nov 1979 type:
           news
   For operations schedule type:
           sched
   Today's quote:
   Love is sentimental measles.
   You have mail.
   % e aver.f4p
   <The file is created in the RAND Editor by hitting  CTRL-B  after
   the  preceeding  command. Once the file has been created the text
   (i.e. FORTRAN code) can be keyed in.>
   % cat aver.f4p
           integer ave
           write(6,1)
   1       format('how many numbers?')
           read(5,2) many
   2       format(i3)
           do 10 i=1, many
           write(6,3)
   3       format('num:')
           read(5,2)
           sum = sum + num
   10      continue
           ave = sum /num
           write(6,4) ave
   4       format('average = ', i4)
           end
   % f4p aver.f4p
   CULC FORTRAN IV PLUS V. 3.2
   None of the errors detected
   0 Errors Detected
   % aver.out
   how many numbers?
   3
   num:
   3
   num:
   5
   num:
   6
   average =    2

                                - 60 -







                                  TUG

   % e aver.f4p
   <The file is edited using the RAND Editor. The coding errors  are
   corrected.>
   % cat aver.f4p
           real ave
           write(6,1)
   1       format('how many numbers?')
           read(5,2) many
   2       format(i3)
           do 10 i=1, many
           write(6,3)
   3       format('num:')
           read(5,2) num
           sum = sum + num
   10      continue
           ave = sum /many
           write(6,4) ave
   4       format('average = ', f6.2)
           end
   % f4p aver.f4p
   CULC FORTRAN IV PLUS V. 3.2
   None of the errors detected
   0 Errors Detected
   % aver.out
   how many numbers?
   3
   num:
   3
   num:
   5
   num:
   6
   average =   4.67
   % diff aver.f4p aver.f4p.bak
   1c1
   <       integer ave
   ---
   >       real ave
   12c12
   <       ave = sum /num
   ---
   >       ave = sum /many
   14c14
   < 4       format('average = ', i4)
   ---
   > 4       format('average = ', f6.2)
   % rm *.bak *.lst *.obj
   glob: [Confirm] y
   % ls -l
   -rw-r-----  1 tml       267 Mar 28 12:25 aver.f4p
   -rwxrwxr-x  1 tml      8508 Mar 28 12:25 aver.out
   % logout

                                - 61 -







                                  TUG

   6.  Appendix B: GENERAL UNIX COMMANDS



   who             Returns info on who is logged on the  system  and
                   what terminal they are logged onto.

   write abc       Allows you to send messages to user abc providing
                   his  permissions  will allow.  After typing write
                   abc, enter the messages you wish  to  send,  ter-
                   minate with ctrl-d. User abc must be logged in.

   pwd             Print Working Directory.  Lets you know where  in
                   the UNIX file system the terminal is positioned.

   ls -l           Creates a directory print of  the  files  at  the
                   current  working  directory.   The  command "dir"
                   does the same.

   chdir aa/bb/cc  The command "chdir" is used with the proper argu-
                   ments  to  move  within  the UNIX filesystem from
                   directory to directory.

   e filename      Is used to call the RAND EDITOR to edit or create
                   the  file  name  supplied.   Don't  use re on any
                   files other than those within the "opr" account.

   opr filename    Will schedule a line printer listing of the  file
                   name  supplied.  Permissions are required for the
                   file.

   cat filename    Will cause the contents of the file  supplied  to
                   be printed or listed on the terminal or console.

   msg/ms          Is used to read or send mail.  See the UNIX manu-
                   als for it's proper use.

   ctrl-d          This combination given to a prompt will cause the
                   terminal to be logged out.














                                - 62 -







                                  TUG

   7.  Appendix C: UNIX COMMAND SUMMARY



   The following is a list of UNIX commands that either were  intro-
   duced  in  the  text  of  the  TUG or directly relate to commands
   introduced in this document.

   as ...............................................  assembler
   assign, ass.....request a peripheral device for dedicated use
   basic ................................................  basic
   bells ...............................  ring the terminal bell
   br, browse ............................  ASCII source browser
   cat ..................................  concatenate and print
   cc ..............................................  C compiler
   cdb .............................................  C debugger
   chdir, cd .........................  change working directory
   chmod ..........................................  change mode
   cmp ......................................  compare two files
   ?,commands...................commands available on the system
   compare,differ .....compare directories and print differences
   compil, load ....................... compile and load command
   copy,move ............  copy (and move) files and directories
   cp ....................................................  copy
   date ................................  print and set the date
   db ...................................................  debug
   dd .................................  convert and copy a file
   ddt .....................................  dynamic C debugger
   deas ....................  release use of a peripheral device
   delete ........................  delete files and directories
   delrem......................delete reminders that are pending
   detach ...........................  detach terminal from jobs
   diff ..........................  differential file comparator
   doc ............................  manuals and local bulletins
   du ....................................  summarize disk usage
   e .........................................  RAND page editor
   ec ...................................  encrypt/decrypt files
   echo ........................................  echo arguments
   ed .............................................  text editor
   f4p ...............................  Fortran IV Plus compiler
   fc ........................................  Fortran compiler
   filex...............................DOS file exchange utility
   fortran ................................  Fortran IV compiler
   ftp ..........................  ARPAnet file transfer program
   grep ...........................  search a file for a pattern
   help ..........................................  ask for help
   hosts ....................  determine status of network hosts
   indent ................  produce an indented C program source
   just ..........  fill and justify indented paragraphs of text
   kill ...................................  terminate a process
   ld .............................................  link editor
   libr .....................................  fortran librarian

                                - 63 -







                                  TUG

   libr .....................  librarian for MACRO-11 and linker
   link ........................................  fortran linker
   linker .............  Linkage editor for MACRO-11 and Fortran
   linkr ..............................  linking loader for UNIX
   lisp ....................list processing language interpreter
   login .......................................  sign onto UNIX
   logout ...................................  logoff the system
   lpq.....................read and maintain line printer queues
   ls ..............................  list contents of directory
   lsm .............................  list file names in columns
   macro .............................  macro assembler for UNIX
   mail .........................  send mail to designated users
   man .........................  run off section of UNIX manual
   mesg ...............................  permit or deny messages
   mkdir .....................................  make a directory
   ms ...................................  message (mail) system
   msg .................................  read mail and messages
   mtio.......................magnetic tape input/output program
   mv ...................................  move or rename a file
   name ................................  find info about a user
   neqn .......................  typeset mathematics on terminal
   news .......................  timely info of general interest
   nice .........................  run a command at low priority
   nroff ..............  Format text for typewriter-like devices
   od ..............................................  octal dump
   opr .........................................  off line print
   passwd ...............................  change login password
   pr ..............................................  print file
   pwd .................................  working directory name
   rc .........................................  Ratfor compiler
   remind ...........  send message or execute at specified time
   rm ...................................  remove (unlink) files
   rmdir .....................................  remove directory
   rpl ..........  replace all occurrences of a string in a file
   rtpip .....................  manipulate RT-11 files from UNIX
   sh .............................  shell (command interpreter)
   sndmsg ...............................  send a message (mail)
   sort, usort ............................  sort or merge files
   spell................................... find spelling errors
   ss .........................  display system (process) status
   stty ................................  set typewriter options
   tab ...............................  changes blanks into tabs
   tabs ..................................  set tabs on terminal
   tail.................................print tail end of a file
   telnet ................  converse with a host via the network
   time ........................................  time a command
   today ..............................  list events of interest
   tp ..........................  manipulate DECtape and magtape
   tr ...........................................  transliterate
   trans................DOS to UNIX assembly language translator
   tty ....................................  get typewriter name
   untab ..............  removes the tabs from one or more files

                                - 64 -







                                  TUG

   where ....................  find location of another terminal
   who ...................................  who is on the system
   write ................................  write to another user


















































                                - 65 -







                                  TUG

                           Table of Contents






   0. Scope of this Manual                                          1

   1. INTRODUCTION                                                  2
     1.1. What is UNIX?                                             2
     1.2. Where is UNIX?                                            3
     1.3. Network Facilities                                        3
     1.4. How to Get an Account                                     3
     1.5. UNIX Security                                             3
     1.6. Consulting and User Assistance                            4
       1.6.1. Terminal Malfunctions                                 5
     1.7. On-line Documentation Aids                                5
       1.7.1. The UNIX Manual                                       6
       1.7.2. Help                                                  6
       1.7.3. News                                                  7
       1.7.4. Other manuals and documents                           7
         1.7.4.1. Documents and User Manuals                        7
         1.7.4.2. Programmer Information Bulletins                  8
     1.8. UNIX Documentation                                        8
       1.8.1. The PWB/UNIX User's Manual                            8
       1.8.2. Documents for the PWB/UNIX Time-Sharing System        9
       1.8.3. Supplement to the PWB/UNIX User's Manual             10
       1.8.4. UNIX Reference Card                                  10
       1.8.5. GTSS Documentation                                   10
     1.9. Advanced Reading                                         11
       1.9.1. Text Processing                                      11
       1.9.2. Programming                                          11
     1.10. Training                                                12

   2. Using UNIX                                                   13
     2.1. Using a Terminal                                         13
       2.1.1. Putting the Terminal On-line                         13
       2.1.2. Logging in                                           13
       2.1.3. Logging Out                                          14
       2.1.4. Useful Information About Your Terminal               14
       2.1.5. Several Common Problems                              14
     2.2. The Printer Terminals                                    15
     2.3. Special Characters                                       16
       2.3.1. Editing Typing Mistakes                              16
       2.3.2. Controlling Typeout                                  16
       2.3.3. Interrupting a Command in Progress                   17
       2.3.4. Terminal End of File                                 17
     2.4. Upper-Lower Case                                         17
     2.5. Files                                                    18
     2.6. File Names and Wild Cards                                19


                                 - i -







                                  TUG

   3. The UNIX Shell                                               21
     3.1. What is the UNIX Shell?                                  21
     3.2. Command Format                                           21
     3.3. Command Abort                                            22
     3.4. Help: Requesting Information on Various Topics           22
       3.4.1. Help: The Shell Program                              22
       3.4.2. The Help Feature Built-In                            23
     3.5. UNIX Shell Variables (*)                                 23
       3.5.1. Using Shell Variables Interactively                  24
         3.5.1.1. User-defined Shell Variables                     24
         3.5.1.2. Pre-defined Shell Variables                      25
       3.5.2. Using the Shell Variables in Shell Programs          25
     3.6. Redirection of Input and Output and Pipes                26
       3.6.1. Redirecting Input and Output                         26
       3.6.2. Pipes                                                26
     3.7. UNIX Commands                                            27
       3.7.1. Information Commands                                 27
       3.7.2. Terminal Status                                      29
       3.7.3. File and Directory Manipulation                      30
       3.7.4. Miscellaneous                                        35
     3.8. Inter-User Communications                                35
     3.9. Languages                                                39
     3.10. Logout and Login                                        39
     3.11. Peripheral Devices                                      40
       3.11.1. Assigning and De-assigning Peripheral Devices       40
       3.11.2. Common Programs for Peripheral Use                  41
     3.12. Games                                                   45

   4. Languages and Editors                                        47
     4.1. C                                                        47
     4.2. FORTRAN                                                  48
       4.2.1. Fortran                                              48
       4.2.2. fc                                                   49
       4.2.3. f4p                                                  49
     4.3. BASIC                                                    50
     4.4. PASCAL                                                   51
     4.5. The Text Editors                                         51
       4.5.1. ED: The UNIX Editor                                  51
       4.5.2. qed                                                  52
       4.5.3. The RAND Editor                                      53
       4.5.4. teco                                                 53
     4.6. The Debugging Programs                                   54
       4.6.1. DB                                                   54
       4.6.2. CDB                                                  55
       4.6.3. DDT                                                  55
       4.6.4. ADB                                                  55
       4.6.5. References                                           55
     4.7. Assemblers                                               56
       4.7.1. AS                                                   56
       4.7.2. MACRO                                                56
     4.8. TRANS                                                    57
     4.9. lisp                                                     57

                                - ii -







                                  TUG

     4.10. PPL                                                     58
     4.11. Cross-Assemblers (*)                                    58

   5. Appendix A: Terminal Session                                 60

   6. Appendix B: GENERAL UNIX COMMANDS                            62

   7. Appendix C: UNIX COMMAND SUMMARY                             63













































                                - iii -




