Mercurial > hg > Members > kono > nitros9-code
changeset 138:d9631713b7cd
Split up the commands into individual files.
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/dump.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,61 @@ +<refentry id="dump"> +<refnamediv> +<refname>DUMP</refname> +<refpurpose>Formatted File Data Dump in Hexadecimal and ASCII</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>DUMP</command> +<arg choice="opt"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command produces a formatted display of the physical data +contents of the path specified which may be a mass storage file or +any other I/O device. If a pathlist is omitted, the standard input +path is used. The output is written to standard output. This command is +commonly used to examine the contents of non-text files. +</para> +<para> +The data is displayed 16 bytes per line in both hexadecimal and +ASCII character format. Data bytes that have non-displayable values +are represented by periods in the character area. +</para> +<para> +The addresses displayed on the dump are relative to the beginning of +the file. Because memory modules are position-independent and stored +on files exactly as they exist in memory, the addresses shown on the +dump correspond to the relative load addresses of memory-module +files. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +DUMP (display keyboard input in hex) +DUMP myfile >/P (dump myfile to printer) +DUMP shortfile +</screen> +</refsect1> + +<refsect1><title>Sample Output</title> +<screen> + Addr 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 2 4 6 8 A C E + ---- ---- ---- ---- ---- ---- ---- ---- ---- ---------------- + 0000 87CD 0038 002A P181 2800 2E00 3103 FFE0 .M.8.*q.(...1..' + 0010 0418 0000 0100 0101 0001 1808 180D 1B04 ................ + 0020 0117 0311 0807 1500 002A 5445 S2CD 5343 .........*TERMSC + 0030 C641 4349 C10E 529E FACIA.R. + + ^ ^ ^ + +starting data bytes in hexadecimal data bytes in +address format ASCII format +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/echo.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,39 @@ +<refentry id="echo"> +<refnamediv> +<refname>ECHO</refname> +<refpurpose>Echo text to output path</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>ECHO</command> +<arg choice="plain"> + &replstart;text&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command echoes its argument to the standard output path. It is +typically used to generate messages in shell procedure files or to +send an initialization character sequence to a terminal. The text +should not include any of the punctuation characters used by the +shell. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +echo >/T2 Hello John how's it going & (echo to T2) + +echo >/term ** warning ** disk about to be scratched 1 + +echo >/p Listing of Transaction File; list trans >/p + + +OS9: echo Here is an important message! +Here is an important message! +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/ex.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,56 @@ +<refentry id="ex"> +<refnamediv> +<refname>EX</refname> +<refpurpose>Execute program as overlay</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>EX</command> +<arg choice="plain"> + &replstart;module name&replend; +</arg> +<arg choice="opt"> + &replstart;modifiers&replend; +</arg> +<arg choice="opt"> + &replstart;parameters&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This a shell built-in command that causes the process executing the +shell to start execution of another program. It permits a transition +from the shell to another program without creating another process, +thus conserving system memory. +</para> +<para> +This command is often used when the shell is called from another +program to execute a specific program, after which the shell is not +needed. For instance, applications which only use BASIC09 need not +waste memory space on SHELL. +</para> +<para> +The "ex" command should always be the last command on a shell input +line because any command line following will never be processed. +</para> +<para> +NOTE: Since this is a built-in SHELL command, it does not appear in +the CMDS directory. +</para> +<para> +For more information see: 4.5, 4.6, 4.9 + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +ex BASIC09 + +tsmon /t1&; tsmon /t2&; ex tsmon /term +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/format.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,65 @@ +<refentry id="format"> +<refnamediv> +<refname>FORMAT</refname> +<refpurpose>Initialize disk media</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>FORMAT</command> +<arg choice="plain"> + &replstart;devname&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to physically initialize, verify, and establish +an initial file structure on a disk. All disks must be formatted +before they can be used on an OS-9 system. +</para> +<para> +NOTE: If the diskette is to be used as a system disk, "OS9gen" or +"cobbler" must be run to create the bootstrap after the disk has +been formatted. +</para> +<para> + +The formatting process works as follows: +</para> + +<orderedlist numeration="arabic"> +<listitem> +<para> +The disk surface is physically initialized and sectored. +</para> +</listitem> +<listitem> +<para> +Each sector is read back and verified. If the sector fails to +verify after several attempts, the offending sector is excluded from +the initial free space on the disk. As the verification is +performed, track numbers are displayed on the standard output +device. +</para> +</listitem> +<listitem> +<para> +The disk allocation map, root directory, and identification sector are written +to the first few sectors of track zero. These +sectors <emphasis>cannot</emphasis> be defective. +</para> +</listitem> +</orderedlist> +<para> +FORMAT will prompt for a disk volume name, which can be up to 32 +characters long and may include spaces or punctuation. This name +can later be displayed using the FREE command. +</para> +<para> +For more information see: 3.10 +</para> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/free.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,51 @@ +<refentry id="free"> +<refnamediv> +<refname>FREE</refname> +<refpurpose>Display free space remaining on mass-storage device</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>FREE</command> +<arg choice="plain"> + &replstart;devname&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command displays the number of unused 256-byte sectors on a +device which are available for new files or for expanding existing +files. The device name given must be that of a mass-storage +multifile device. "Free" also displays the disk's name, creation +date, and cluster size. +</para> +<para> +Data sectors are allocated in groups called "clusters". The number +of sectors per cluster depends on the storage capacity and physical +characteristics of the specific device. This means that small +amounts of free space may not be divisible into as many files. For +example, if a given disk system uses 8 sectors per cluster, and a +"free" command shows 32 sectors free, a maximum of four new files +could be created even if each has only one cluster. +</para> +<para> +For more information see: 3.10 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: free +BACKUP DATA DISK created on: 80/06/12 +Capacity: 1,232 sectors (1-sector clusters) +1,020 free sectors, largest block 935 sectors + +OS9: free /D1 +OS-9 Documentation Disk created on: 81/04/13 +Capacity: 1,232 sectors (1-sector clusters) +568 Free sectors, largest block 440 sectors +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/ident.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,115 @@ +<refentry id="ident"> +<refnamediv> +<refname>IDENT</refname> +<refpurpose>Print OS-9 module identification</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>IDENT</command> +<arg choice="opt"> + <option>-opts</option> +</arg> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="opt"> + <option>-opts</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to display header information from OS-9 memory +modules. IDENT displays the module size, CRC bytes (with verification), and for +program and device driver modules, the execution +offset and the permanent storage requirement bytes. IDENT will +print and interpret the type/language and attribute/revision bytes. +In addition, IDENT displays the byte immediately following the +module name since most Microware-supplied modules set this byte to +indicate the module edition. +</para> +<para> +IDENT will display all modules contained in a disk file. If the +"-m" option appears, &replstart;path&replend; is assumed to be a module in memory. +</para> +<para> +If the "-v" option is specified, the module CRC is not verified. +</para> +<para> +The "-x" option implies the pathlist begins in the execution +directory. +</para> +<para> +The "-s" option causes IDENT to display the. following module +information on a single line: +</para> +<simplelist> +<member> +Edition byte (first byte after module name) +</member> +<member> +Type/Language byte +</member> +<member> +Module CRC +</member> +<member> +A "." if the CRC verifies correctly, "?" if incorrect. +(IDENT will leave this field blank if the "-v" option appears.) +</member> +<member> +Module name +</member> +</simplelist> +</refsect1> + +<refsect1><title>Examples</title> +<screen> +OS9: ident -m ident +Header for: Ident <Module name> +Module size: $06A5 #1701 <Module size> +Module CRC: $1CE78A (Good) <Good or Bad> +Hdr parity: $8B <Header parity> +Exec. off: $0222 #546 <Execution offset> +Data size: $0CA1 #3233 <Permanent storage requirement> +Edition: $05 #5 <First byte after module name> +Ty/La At/Rv: $11 $81 <Type/Language Attribute/Revision> +Prog mod, 6809 obj, re-en <Module type, Language, Attribute> +</screen> +<screen> +OS9: ident /d0/os9boot -s + 1 $C0 $A366DC . OS9p2 + 83 $C0 $7FC336 . Init + 1 $11 $39BA94 . SysGo + 1 $C1 $402573 . IOMan + 3 $D1 $EE937A . REF + 82 $F1 $526268 . D0 + 82 $F1 $D65245 . D1 + 82 $F1 $E32FFE . D2 + 1 $D1 $F944D7 . SCF + 2 $E1 $F9FE37 . ACIA + 83 $F1 $765270 . TERM + 83 $F1 $B4396C . T1 + 83 $F1 $63B73B . T2 + 83 $F1 $0F9B78 . T3 + 83 $F1 $F83EB9 . T4 + 83 $F1 $D6DD9A . T5 + 3 $E1 $3EE015 . PIA + 83 $F1 $12A43B . P + 2 $D1 $BBC1EE . PipeMan + 2 $E1 $5B2B56 . Piper + 80 $F1 $CC06AF . Pipe + 2 $C1 $248B2C . Clock + ^ ^ ^ ^ ^ + | | | | | + | | | | Module name + | | | CRC check " " if -v, "." if OK, "?" if bad + | | CRC value + | Type/Language byte + Edition byte (first byte after name) +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/kill.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,65 @@ +<refentry id="kill"> +<refnamediv> +<refname>KILL</refname> +<refpurpose>Abort a process</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>KILL</command> +<arg choice="plain"> + &replstart;procID&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This shell "built in" command sends an "abort" signal to the +process having the process ID number specified. The process to be +aborted must have the same user ID as the user that executed the +command. The "procs" command can be used to obtain the process ID +numbers. +</para> +<para> +NOTE: If a process is waiting for I/O, it may not die until it +completes the current I/O operation, therefore, if you KILL a +process and the PROCS command shows it still exists, it is probably +waiting for receive a line of data from a terminal before it can +die. + +Since this is a built-in SHELL command, it does not appear in the +CMDS directory. + +For more information see: 4.5, 5.2, PROCS + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +kill 5 + +kill 22 + +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 20 2 0 active 2 Shell <TERM + 20 1 0 waiting 1 Sysgo <TERM + 20 3 0 sleeping 20 Copy <TERM + +OS9: kill 3 +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 20 2 0 active 2 Shell <TERM + 20 1 0 waiting 1 Sysgo <TERM + +OS9: +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/link.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,37 @@ +<refentry id="link"> +<refnamediv> +<refname>LINK</refname> +<refpurpose>Link module into memory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LINK</command> +<arg choice="plain"> + &replstart;memory module name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command is used to "lock" a previously loaded module into +memory. The link count of the module specified is incremented by one +each time it is "linked". The "unlink" command is +used to "unlock" +the module when it is no longer needed. +</para> +<para> +For more information see: 5.4, 5.4.1, 5.4.2, 5.4.3 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9: LINK edit + +OS9: LINK myprogram +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/list.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,64 @@ +<refentry id="list"> +<refnamediv> +<refname>LIST</refname> +<refpurpose>List the contents of a text file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LIST</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &repeatst; &replstart;path&replend; &repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command copies text lines from the path(s) given as parameters +to the standard output path. The program terminates upon reaching +the end-of-file of the last input path. If more than one path is +specified, the first path will be copied to standard output, the +second path will be copied next, etc. +</para> +<para> +This command is most commonly used to examine or print text files. +</para> +<para> +For more information see: 2.3, 3.9.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +list /d0/startup >/P & (output is redirected to printer) + +list /D1/user5/document /d0/myfile /d0/Bob/text + +list /TERM >/p (copy keyboard to printer - use + "escape" key to terminate input) +</literallayout> +<screen> + +OS9: build animals +? cat +? cow +? dog +? elephant +? bird +? fish +? [RETURN] + +OS9: list animals +cat +cow +dog +elephant +bird +fish +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/load.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,58 @@ +<refentry id="load"> +<refnamediv> +<refname>LOAD</refname> +<refpurpose>Load module(s) from file into memory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LOAD</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +The path specified is opened and one or more modules is read from it +and loaded into memory. The names of the modules are added to the +module directory. If a module is loaded that has the same name and +type as a module already in memory, the module having the highest +revision level is kept. +</para> +<para> +For more information see: 3.9.4, 5.4.1, 5.4.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> + load new_program +</literallayout> + +<screen> + +OS9:mdir + + Module Directory at 13:36:47 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN REF +SCF ACIA TERM T1 T2 +T3 P PIA CDS H1 +Sysgo Clock Shell Tsmon Copy +Mdir + +OS9:load edit +OS9:mdir + + Module Directory at 13:37:14 +DCB4 D0 D1 D2 D3 +OS9P2 INIT OS9 IOMAN REF +SCF ACIA TERM T1 T2 +T3 P PIA CDS H1 +Sysgo Clock Shell Tsmon Copy +Mdir EDIT +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/login.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,129 @@ +<refentry id="login"> +<refnamediv> +<refname>LOGIN</refname> +<refpurpose>Timesharing System Log-In</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>LOGIN</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Login is used in timesharing systems to provide log-in security. It +is automatically called by the timesharing monitor "tsmon", or can +be used after initial log-in to change a terminal's user. +</para> +<para> +Login requests a user name and password, which is checked against a +validation file. If the information is correct, the user's system +priority, user ID, and working directories are set up according to +information stored in the file, and the initial program specified in +the password file is executed (usually SHELL). If the user cannot +supply a correct user name and password after three attempts, the +process is aborted. The validation file is called "PASSWORD" and +must be present in the directory "/d0/SYS". The file contains one or +more variable-length text records, one for each user name. Each +record has the following fields, which are delimited by commas: +</para> +<para> +1. User name (up to 32 characters, may include spaces). If this +field is empty, any name will match. +</para> +<para> +2. Password (up to 32 characters, may include spaces) If this field +is omitted, no password is required by the specific use. +</para> +<para> +3. User index (ID) number (from 0 to 65535, 0 is superuser). +This number is used by the file security system and as the system-wide +user ID to identify all processes initiated by the user. The +system manager should assign a unique ID to each potential user. +(See 3.8) +</para> +<para> +4. Initial process (CPU time) priority: 1 - 255 (see 5.2) +</para> +<para> +5. Pathlist of initial execution directory (usually /d0/CMDS) +</para> +<para> +6. Pathlist of initial data directory (specific user's directory) +</para> +<para> +7. Name of initial program to execute (usually "shell"). +NOTE: This is not a shell command line. +</para> +<para> +Here's a sample validation file: +</para> + +<screen> +superuser,secret,0,255,.,.,shell +steve,open sesame,3,128,.,/d1/STEVE,shell +sally,qwerty,10,100,/d0/BUSINESS,/d1/LETTERS,wordprocessor +bob,,4,128,.,/d1/BOB,Basic09 +</screen> + +<para> +To use the login command, enter: +</para> +<literallayout> +login +</literallayout> +<para> +This will cause prompts for the user's name and (optionally) +password to be displayed, and if answered correctly, the user is +logged into the system. Login initializes the user number, working +execution directory, working data directory, and executes the +initial program specified by the password file. The date, time and +process number (which is <emphasis>not</emphasis> the same as +the user ID, see 5.3) are also displayed. +</para> +<para> +Note: if the shell from which "login" was called will not be needed +again, it may be discarded by using the EX command to start the +LOGIN command. For example: +</para> +<literallayout> +ex login +</literallayout> +<refsect2> +<title>Logging Off the System</title> +<para> +To log off the system, the initial program specified in the password +file must be terminated. For most programs (including shell) this +may be done by typing an end of file character (escape) as the first +character on a line. +</para> +</refsect2> +<refsect2> +<title>Displaying a "Message-of-the-Day"</title> +<para> +If desired, a file named "motd" appearing in the SYS directory will +cause LOGIN to display it's contents on the user's terminal after +successful login. This file is not required for LOGIN to operate. +</para> +<para> +For more information see: tsmon, 2.5, 3.8, 5.3 +</para> +</refsect2> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: login + +OS-9 Level 1 Timesharing System Version 1.2 82/12/04 13:02:22 + +User name?: superuser +Password: secret + +Process #07 logged 81/12/04 13:03:00 + +Welcome! +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/makdir.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,45 @@ +<refentry id="makdir"> +<refnamediv> +<refname>MAKDIR</refname> +<refpurpose>Create directory file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MAKDIR</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Creates a new directory file acdording to the pathlist given. The +pathlist must refer to a parent directory for which the user has +write permission. +</para> +<para> +The new directory is initialized and initially does not contain +files except for the "." and ".." pointers to its parent directory +and itself, respectively (see 3.7.3). All access permissions are +enabled (except sharable). +</para> +<para> +It is customary (but not mandatory) to capitalize directory names. +</para> +<para> +For more information see: 3.3, 3.4, 3.5,3.7.3, 3.9.5 +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +makdir /d1/STEVE/PROJECT + +makdir DATAFILES + +makdir ../SAVEFILES +</literallayout> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/mdir.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,62 @@ +<refentry id="mdir"> +<refnamediv> +<refname>MDIR</refname> +<refpurpose>Display Module Directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MDIR</command> +<arg choice="opt"> + <option>e</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays the present module names in the system module directory, +i.e., all modules currently resident in memory. For example: +</para> +<screen> +OS9: mdir + + Module Directory at 14:44:35 +D0 Pipe OS9 OS9P2 +Init Boot DDisk D1 +KBVDIO TERM IOMan RBF +SCF SysGo Clock Shell +PRINTER P PipeMan Piper +Mdir +</screen> +<para> +If the "e" option is given, a full listing of the physical address, +size, type, revision level, reentant attribute, user count, and name +of each module is displayed. All numbers shown are in hexadecimal. +</para> +<screen> +OS9: MDIR E + +Module Directory at 10:55:04 + +ADDR SIZE TY RV AT UC NAME +---- ---- -- -- -- -- -------- +C305 2F F1 1 R D0 +F059 7EB C1 1 R OS9 +F852 4F4 C1 1 R OS9P2 +FD46 2E CO 1 R INIT +C363 798 E1 1 R 2 KBVDIO +CAFB 38 F1 1 R 2 TERM +</screen> +<para> + +WARNING: Many of the modules listed by MDIR are OS-9 system modules +and NOT executable as programs: always check the module type code +before running a module if you are not familiar with it! +</para> +<para> +For more information see: 5.4.1 +</para> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/merge.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,37 @@ +<refentry id="merge"> +<refnamediv> +<refname>MERGE</refname> +<refpurpose>Copy and Combine Files to Standard Output</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MERGE</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &repeatst; &replstart;path&replend; &repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command copies multiple input files specified by the pathlists +given as parameters to the standard output path. it is commonly +used to combine several files into a single output file. Data is +copied in the order the pathlists are given. MERGE does no output +line editing (such as automatic line feed). The standard output is +generally redirected to a file or device. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: merge file1 file2 file3 file4 >combined.file + +OS9: merge compile.list asm.list >/printer +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/mfree.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,40 @@ +<refentry id="mfree"> +<refnamediv> +<refname>MFREE</refname> +<refpurpose>Display Free System RAM</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>MFREE</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays a list of which areas of memory are not presently in use +and available for assignment. The address and size of each free +memory block are displayed. The size is given as the number of 256-byte +pages. This information is useful to detect and correct memory +fragmentation (see 5.4.3). +</para> +<para> +For more information see: 5.4, 5.4.3 + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: mfree + + Address pages +--------- ----- + 700- 7FF 1 + B00-AEFF 164 +B100-B1FF 1 + +Total pages free = 166 +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/os9gen.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,94 @@ +<refentry id="os9gen"> +<refnamediv> +<refname>OS9GEN</refname> +<refpurpose>Build and Link a Bootstrap File</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>OS9GEN</command> +<arg choice="plain"> + &replstart;device name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +OS9Gen is used to create and link the "OS9Boot" file required on any +disk from which OS-9 is to be bootstrapped. OS9Gen is used to add +modules to an existing boot or to create an entirely new boot file. +If an exact copy of the existing OS9Boot file is desired, the +COBBLER command should be used instead. +</para> +<para> +The name of the device on which the "OS9Boot" file is to be +installed is passed to OS9Gen as a command line parameter. OS9Gen then +creates a working file called "TempBoot" on the device specified. +Next it reads file names (pathlists) from its standard input, one +pathlist per line. Every file named is opened and copied to +"TempBoot". This is repeated until end-of-file or a blank line is +reached on OS9Gen's standard input. All boot files must contain the +OS-9 component modules listed in section 6.1. +</para> +<para> +After all input files have been copied to "TempBoot", the old +"OS9Boot" file, if present, is deleted. "TempBoot" is then renamed +to "OS9Boot", and its starting address and size is linked in the +disk's Identification Sector (LSN 0) for use by the OS-9 bootstrap +firmware. +</para> +<para> +WARNING: Any "OS9Boot" file must be stored in physically contiguous +sectors. Therefore, OS9Gen is normally used on a freshly formatted +disk. If the "OS9Boot" file is fragmented, OS9Gen will print a +warning message indicated the disk cannot be used to bootstrap OS-9. +</para> +<para> +The list of file names given to OS9Gen can be entered from a keyboard, or +OS9Gen's standard input may be redirected to a text file +containing a list of file names (pathlists) . If names are entered +manually, no prompts are given, and the end-of-file key (usually +ESCAPE) or a blank line is entered after the line containing the +last pathlist. +</para> +<para> +For more information see: 6.0, 6.1, 6.6 +</para> +</refsect1> +<refsect1><title>Examples</title> +<para> +To manually install a boot file on device "d1" which is an exact +copy of the "OS9Boot" file on device "d0": +</para> +<screen> +OS9: os9gen /d1 (run OS9Gen) +/d0/os9boot (enter file to be installed) +[ESCAPE] (enter end-of-file) +</screen> +<para> +To manually install a boot file on device "d1" which is a copy of +the "OS9Boot" file on device "do" with the addition of +modules stored in the files "/d0/tape.driver" and "/d2/video.driver": +</para> +<screen> +OS9: os9gen /d1 (run OS9Gen) +/d0/os9boot (enter main boot file name) +/d0/tape.driver (enter name of first file to be added) +/d2/video.driver (enter name of second file to be added) +[ESCAPE] (enter end-of-file) +</screen> +<para> +As above, but automatically by redirecting OS9Gen standard input: +</para> +<screen> +OS9: build /d0/bootlist (use "build" to create file "bootlist") +? /d0/os9boot (enter first file name) +? /d0/tape.driver (enter second file name) +? /d2/video.driver (enter third file name) +? [RETURN] (terminate "build") +OS9: os9gen /d1 </d0/bootlist (run OS9gen with redirected input) +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/printerr.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,49 @@ +<refentry id="printerr"> +<refnamediv> +<refname>PRINTERR</refname> +<refpurpose>Print Full Text Error Messages</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PRINTERR</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command replaces the basic OS-9 error printing routine (F$PERR +service request) which only prints error code numbers, with a +routine the reads and displays textual error messages from the file +"/d0/SYS/errmsg". Printerr's effect is system-wide. +</para> +<para> +A standard error message file is supplied with OS-9. This file can +be edited or replaced by the system manager. The file is a normal +text file with variable length line. Each error message line begins +with the error number code (in ASCII characters), a delimiter, and +the error message text. The error messages need not be in any +particular order. Delimiters are spaces or any character numerically lower then +$20. Any line having a delimiter as its first +character is considered a contintjation of the previous line(s) which +permits multi-line error messages. +</para> +<para> +WARNING: Once the printerr command has been used, it can not be undone. Once +installed, the PRINTERR module should not be unlinked. +PRINTERR uses the current user's stack for an I/O buffer, so users +are encouraged to reserve reasonably large stacks. +</para> +<para> +For more information see: 4.7, 6.2 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> + +OS9: printerr + +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/procs.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,48 @@ +<refentry id="procs"> +<refnamediv> +<refname>PROCS</refname> +<refpurpose>Display Processes</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PROCS</command> +<arg choice="opt"> + <option>e</option> +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Displays a list of processes running on the system. Normally only +processes having the user's ID are listed, but if the "e" option is +given, processes of all users are listed. The display is a +"snapshot" taken at the instant the command is executed: processes +can switch states rapidly, usually many times per second. +</para> +<para> +PROCS shows the user and process ID numbers, priority, state +(process status), memory size (in 256 byte pages), primary program +module, and standard input path. +</para> +<para> +For more information see: 5.1, 5.2, 5.3 +</para> +</refsect1> +<refsect1><title>Examples</title> +<para> +Level One Example: +</para> +<screen> +User# Id pty state Mem Primary module +---- --- --- -------- --- -------------- + 0 2 0 active 2 Shell + 0 1 0 waiting 1 SysGo + 1 3 1 waiting 2 Tsmon + 1 4 1 waiting 4 Shell + 1 5 1 active 64 Basic09 +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/pwd.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,42 @@ +<refentry id="pwd"> +<refnamediv> +<refname>PWD/PXD</refname> +<refpurpose>Print Working Directory / Print Execution Directory</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>PWD</command> +</cmdsynopsis> +<cmdsynopsis> +<command>PXD</command> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +PWD displays a pathlist that shows the path from the root +directory to the user's current data directory. It can be used by +programs to discover the actual physical location of files, or by +humans who get lost in the file system. PXD is identical except +that is shows the pathlist of the user's current execution directory. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: chd /D1/STEVE/TEXTFILES/MANUALS +OS9: pwd +/D1/STEVE/TEXTFILES/MANUALS +OS9: chd .. +OS9: pwd +/D1/STEVE/TEXTFILES +OS9: chd .. +OS9: pwd +/D1/STEVE + +OS9: pxd +/D0/CMDS +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/rename.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,48 @@ +<refentry id="rename"> +<refnamediv> +<refname>RENAME</refname> +<refpurpose>Change file name</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>RENAME</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &replstart;new name&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Gives the mass storage file specified in the pathlist a new name. +The user must have write permission for the file to change its name. +It is not possible to change the names of devices, ".", or +".." +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +rename blue purple + +rename /D3/user9/test temp +</literallayout> + +<screen> +OS9: dir + + Directory of . 16:22:53 +myfile animals + +OS9:rename animals cars +OS9:dir + + Directory of . 16:23:22 +myfile cars +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/save.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,43 @@ +<refentry id="save"> +<refnamediv> +<refname>SAVE</refname> +<refpurpose>Save memory module(s) on a file</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SAVE</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="plain"> + &replstart;modname&replend; +</arg> +<arg choice="plain"> + &repeatst;&replstart;modname&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +Creates a new file and writes a copy of the memory module(s) +specified on to the file. The module name(s) must exist in the +module directory when saved. The new file is given access +permissions for all modes except public write. +</para> +<para> +Note: SAVE's default directory is the current data directory. +Executable modules should generally be saved in the default +execution directory. +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +save wordcount wcount + +save /d1/mathpack add sub mul div +</literallayout> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/setime.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,45 @@ +<refentry id="setime"> +<refnamediv> +<refname>SETIME</refname> +<refpurpose>Activate and set system clock</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SETIME</command> +<arg choice="opt">y,m,d,h,m,s</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command sets the system date and time, then activates the real +time clock. The date and time can be entered as parameters, or if no +parameters are given, SETIME will issue a prompt. Numbers are one +or two decimal digits using space, colon, semicolon or slash +delimiters. OS-9 system time uses the 24 hour clock, i.e., 1520 is +3:20 PM. +</para> +<para> +IMPORTANT NOTE: This command must be executed before OS-9 can +perform multitasking operations. If the system does not have a real +time clock this command should still be used to set the date for the +file system. +</para> +<para> +SYSTEMS WITH BATTERY BACKED UP CLOCKS: Setime should still be run to +start time-slicing, but only the <emphasis>year</emphasis> need be given, +the date and time will be read from the clock. +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: setime 82,12,22,1545 (Set to: Dec. 12, 1981, 3:45 PM) + +OS9: setime 821222 154500 (Same as above) + +OS9: setime 82 (For system with battery-backup clock) +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/setpr.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,60 @@ +<refentry id="setpr"> +<refnamediv> +<refname>SETPR</refname> +<refpurpose>Set Process Priority</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SETPR</command> +<arg choice="plain"> + &replstart;procID&replend; +</arg> +<arg choice="plain"> + &replstart;number&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command changes the CPU priority of a process. It may only be +used with a process having the user's ID. The process number is a +decimal number in the range of 1 (lowest) to 255. The "procs" +command can be used to obtain process ID numbers and present priority. +</para> +<para> +NOTE: This command does not appear in the CMDS directory as it is +built-in to the SHELL. +</para> +<para> +For more information see: 5.1, PROCS +</para> +</refsect1> +<refsect1><title>Examples</title> +<literallayout> +setpr 8 250 (change process #8 priority to 250) +</literallayout> + +<screen> +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 0 3 0 waiting 2 Shell <TERM + 0 2 0 waiting 2 Shell <TERM + 0 1 0 waiting 1 Sysgo <TERM + + +OS9: setpr 3 128 +OS9: procs + +User # Id pty state Mem Primary module +----- --- --- -------- --- -------------- + 0 3 128 active 2 Shell <TERM + 0 2 0 waiting 2 Shell <TERM + 0 1 0 waiting 1 Sysgo <TERM +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/shell.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,83 @@ +<refentry id="shell"> +<refnamediv> +<refname>SHELL</refname> +<refpurpose>OS-9 Command Interpreter</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SHELL</command> +<arg choice="plain">&replstart;arglist&replend;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +The Shell is OS-9's command interpreter program. It reads data from +its standard input path (the keyboard or a file), and interprets the +data as a sequence of commands. - The basic function of the shell is +to initiate and control execution of other OS-9 programs. +</para> +<para> +The shell reads and interprets one text line at a time from the +standard input path. After interpretation of each line it reads +another until an end-of-file condition occurs, at which time it +terminates itself. A special case is when the shell is called from +another program, in which case it will take the parameter area (rest +of the command line) as its first line of input. If this command +line consists of "built in" commands only, more lines will be read +and processed; otherwise control will return to the calling program +after the single command line is processed. +</para> +<para> +The rest of this description is a technical specification of the +shell syntax. Use of the Shell is described fully in Chapters 2 +and 4 of this manual. +</para> +</refsect1> +<refsect1><title>Shell Input Line Formal Syntax</title> +<synopsis> +&replstart;pgm line&replend; := &replstart;pgm&replend; {&replstart;pgm&replend;} +&replstart;pgm&replend; := [&replstart;params&replend;] [ &replstart;name&replend; [&replstart;modif&replend;] [&replstart;pgm params&replend;] [&replstart;modif&replend;] ] [&replstart;sep&replend;] + +Program Specifications + +&replstart;name&replend; := &replstart;module name&replend; + := &replstart;pathlist&replend; + := ( &replstart;pgm list&replend; ) + +Parameters + +&replstart;params&replend;:= &replstart;param&replend; { &replstart;delim&replend; &replstart;param&replend; } +&replstart;delim&replend; := space or comma characters +&replstart;param&replend; := ex &replstart;name&replend; [&replstart;modif&replend;] chain to program specified + := chd &replstart;pathlist&replend; change working directory + := kill &replstart;procID&replend; send abort signal to process + := setpr&replstart;procID&replend; &replstart;pty&replend; change process priority + := chx &replstart;pathlist&replend; change execution directory + := w wait for any process to die + := p turn "OS9:" prompting on + := -p turn prompting off + := t echo input lines to std output + := -t don't echo input lines + := -x dont abort on error + := x abort on error + := * &replstart;text&replend; comment line: not processed +&replstart;sep&replend; := ; sequential execution separator + := & concurrent execution separator + := ! pipeline separator + := &replstart;cr&replend; end-of-line (sequential execution separator) + + +Modifiers + +&replstart;modif&replend; := &replstart;mod&replend; { &replstart;delim&replend; &replstart;mod&replend; } +&replstart;mod&replend; := < &replstart;pathlist&replend; redirect standard input + := > &replstart;pathlist&replend; redirect standard output + := >> &replstart;pathlist&replend; redirect standard error output + := # &replstart;integer&replend; set process memory size in pages + := # &replstart;integer&replend; K set program memory size in 1K increments +</synopsis> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/sleep.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,36 @@ +<refentry id="sleep"> +<refnamediv> +<refname>SLEEP</refname> +<refpurpose>Suspend process for period of time</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>SLEEP</command> +<arg choice="plain"> + &replstart;tick count&replend; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> +This command puts the user's process to "sleep" for a number of +clock ticks. It is generally used to generate time delays or to +"break up" CPU-intensive jobs. The duration of a tick is 16.66 +milliseconds. +</para> +<para> +A tick count of 1 causes the process to "give up" its current time +slide. A tick count of zero causes the process to sleep +indefinitely (usually awakened by a signal) + +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +OS9: sleep 25 +</screen> +</refsect1> +</refentry> +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/tee.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,56 @@ +<refentry id="tee"> +<refnamediv> +<refname>TEE</refname> +<refpurpose>Copy standard input to multiple output paths</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>TEE</command> +<arg choice="plain"> + &repeatst;&replstart;path&replend;&repeaten; +</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> + +<para> + +TEE + +Copy standard input to multiple output paths + +Syntax: Tee {&replstart;path&replend;} + + + +This command is a filter (see 4.3.3) that copies all text lines from +its standard input path to the standard output path +<emphasis>and</emphasis> any number +of additional output paths whose pathlists are given as parameters. +</para> +<para> +The example below uses a pipeline and TEE to simultaneously send the +output listing of the "dir" command to the terminal, printer, and a +disk file: +</para> +<screen> +dir e ! tee /printer /d0/dir.listing +</screen> +<para> +The following example sends the output of an assembler listing to a +disk file and the printer: +</para> +<screen> +asm pgm.src l ! tee pgm.list >/printer +</screen> +<para> +The example below "broadcasts" a message to four terminals: +</para> +<screen> +echo WARNING System down in 10 minutes ! tee /t1 /t2 /t3 /t4 +</screen> +</refsect1> +</refentry> +