Mercurial > hg > Members > kono > nitros9-code
changeset 133:40f5c43c8c03
Split up the commands into individual files.
| author | roug |
|---|---|
| date | Sun, 07 Jul 2002 08:58:56 +0000 |
| parents | 9122874c278c |
| children | 52af9581ef1e |
| files | docs/nitros9guide/attr.refentry docs/nitros9guide/os9guide.docbook |
| diffstat | 2 files changed, 160 insertions(+), 3214 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/nitros9guide/attr.refentry Sun Jul 07 08:58:56 2002 +0000 @@ -0,0 +1,68 @@ +<refentry id="attr"> +<refnamediv> +<refname id="attrname">ATTR</refname> +<refpurpose>Change file security attributes</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>ATTR</command> +<arg choice="plain"> + &replstart;path&replend; +</arg> +<arg choice="opt">&repeatst; &replstart;permission abbreviations&replend; &repeaten;</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para> + +This command is used to examine or change the security permissions +of a file. To enter the command, type "ATTR" followed by the +pathlist for the file who's security permissions are to be changed, +followed by a list of permissions which are to be turned on or off. +A permission is turned on by giving its abbreviation, or turned off +by preceding its abbreviation with a minus sign. Permissions not +explicitly named are not affected. If no permissions are given the +current file attributes will be printed. You can not change the +attributes of a file which you do not own (except for user zero, who +can change the attributes of any file in the system). +</para> +<para> +The file permission abbreviations are: +</para> +<literallayout> + d = Directory file + s = Sharable file + r = Read permit to owner + w = Write permit to owner + e = Execute permit to owner +pr = Read permit to public +pw = Write permit to public +pe = Execute permit to public +</literallayout> + +<para> +The ATTR command may be used to change a directory file to a +non-directory file if all entries have been deleted from it. Since the +DEL command will only delete non-directory files, this is the only +way a directory may be deleted. You cannot change a non-directory +file to a directory file with this command (see MAKDIR). +</para> +<para> +For more information see: 3.8, 3.8.1 +</para> +</refsect1> +<refsect1><title>Examples</title> +<screen> +attr myfile -pr -pw + +attr myfile r w e pr rw pe + + +attr datalog +-s-wr-wr +</screen> +</refsect1> +</refentry> +
--- a/docs/nitros9guide/os9guide.docbook Sun Jul 07 05:28:42 2002 +0000 +++ b/docs/nitros9guide/os9guide.docbook Sun Jul 07 08:58:56 2002 +0000 @@ -3,6 +3,52 @@ <!ENTITY replend ">"> <!ENTITY repeatst "{"> <!ENTITY repeaten "}"> + <!ENTITY attrref SYSTEM "attr.refentry"> + <!ENTITY backupref SYSTEM "backup.refentry"> + <!ENTITY binexref SYSTEM "binex.refentry"> + <!ENTITY buildref SYSTEM "build.refentry"> + <!ENTITY chdref SYSTEM "chd.refentry"> + <!ENTITY cmpref SYSTEM "cmp.refentry"> + <!ENTITY cobblerref SYSTEM "cobbler.refentry"> + <!ENTITY copyref SYSTEM "copy.refentry"> + <!ENTITY dateref SYSTEM "date.refentry"> + <!ENTITY dcheckref SYSTEM "dcheck.refentry"> + <!ENTITY delref SYSTEM "del.refentry"> + <!ENTITY deldirref SYSTEM "deldir.refentry"> + <!ENTITY dirref SYSTEM "dir.refentry"> + <!ENTITY displayref SYSTEM "display.refentry"> + <!ENTITY dsaveref SYSTEM "dsave.refentry"> + <!ENTITY dumpref SYSTEM "dump.refentry"> + <!ENTITY echoref SYSTEM "echo.refentry"> + <!ENTITY exref SYSTEM "ex.refentry"> + <!ENTITY formatref SYSTEM "format.refentry"> + <!ENTITY freeref SYSTEM "free.refentry"> + <!ENTITY identref SYSTEM "ident.refentry"> + <!ENTITY killref SYSTEM "kill.refentry"> + <!ENTITY linkref SYSTEM "link.refentry"> + <!ENTITY listref SYSTEM "list.refentry"> + <!ENTITY loadref SYSTEM "load.refentry"> + <!ENTITY loginref SYSTEM "login.refentry"> + <!ENTITY makdirref SYSTEM "makdir.refentry"> + <!ENTITY mdirref SYSTEM "mdir.refentry"> + <!ENTITY mergeref SYSTEM "merge.refentry"> + <!ENTITY mfreeref SYSTEM "mfree.refentry"> + <!ENTITY os9genref SYSTEM "os9gen.refentry"> + <!ENTITY printerrref SYSTEM "printerr.refentry"> + <!ENTITY procsref SYSTEM "procs.refentry"> + <!ENTITY pwdref SYSTEM "pwd.refentry"> + <!ENTITY renameref SYSTEM "rename.refentry"> + <!ENTITY saveref SYSTEM "save.refentry"> + <!ENTITY setimeref SYSTEM "setime.refentry"> + <!ENTITY setprref SYSTEM "setpr.refentry"> + <!ENTITY shellref SYSTEM "shell.refentry"> + <!ENTITY sleepref SYSTEM "sleep.refentry"> + <!ENTITY teeref SYSTEM "tee.refentry"> + <!ENTITY tmoderef SYSTEM "tmode.refentry"> + <!ENTITY tsmonref SYSTEM "tsmon.refentry"> + <!ENTITY unlinkref SYSTEM "unlink.refentry"> + <!ENTITY verifyref SYSTEM "verify.refentry"> + <!ENTITY xmoderef SYSTEM "xmode.refentry"> ]> <book id="os9guide" lang="en"> <bookinfo> @@ -3469,3220 +3515,52 @@ <section> <title>Commands</title> -<refentry id="attr"> -<refnamediv> -<refname id="attrname">ATTR</refname> -<refpurpose>Change file security attributes</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>ATTR</command> -<arg choice="plain"> - &replstart;path&replend; -</arg> -<arg choice="opt">&repeatst; &replstart;permission abbreviations&replend; &repeaten;</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> - -This command is used to examine or change the security permissions -of a file. To enter the command, type "ATTR" followed by the -pathlist for the file who's security permissions are to be changed, -followed by a list of permissions which are to be turned on or off. -A permission is turned on by giving its abbreviation, or turned off -by preceding its abbreviation with a minus sign. Permissions not -explicitly named are not affected. If no permissions are given the -current file attributes will be printed. You can not change the -attributes of a file which you do not own (except for user zero, who -can change the attributes of any file in the system). -</para> -<para> -The file permission abbreviations are: -</para> -<literallayout> - d = Directory file - s = Sharable file - r = Read permit to owner - w = Write permit to owner - e = Execute permit to owner -pr = Read permit to public -pw = Write permit to public -pe = Execute permit to public -</literallayout> - -<para> -The ATTR command may be used to change a directory file to a -non-directory file if all entries have been deleted from it. Since the -DEL command will only delete non-directory files, this is the only -way a directory may be deleted. You cannot change a non-directory -file to a directory file with this command (see MAKDIR). -</para> -<para> -For more information see: 3.8, 3.8.1 -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -attr myfile -pr -pw - -attr myfile r w e pr rw pe - - -attr datalog --s-wr-wr -</screen> -</refsect1> -</refentry> - -<refentry id="backup"> -<refnamediv> -<refname id="backupname">BACKUP</refname> -<refpurpose>Make a backup copy of a disk</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>BACKUP</command> -<arg choice="opt"> - <option>e</option> -</arg> -<arg choice="opt"> - <option>s</option> -</arg> -<arg choice="opt"> - <option>-v</option> -</arg> -<arg choice="opt">&replstart;devname&replend; - <arg choice="opt">&replstart;devname&replend;</arg></arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to physically copy all data from one device to -another. A physical copy is performed sector by sector without -regard to file structures. In almost all cases the devices -specified mun.t have the exact same format (size, density, etc.) and -must not have defective sectors. -</para> -<para> -If both device name are omitted the names "/d0" and "/d1" are -assumed. If the second device name is omitted, a single unit backup -will be performed on the drive specified. -</para> -<para> -The options are: -</para> -<literallayout> - E = Exit if any read error occurs. - S = Print single drive prompt message. - -V = Do not verify. -#nK = more memory makes backup run faster -</literallayout> -</refsect1> -<refsect1><title>Examples</title> -<screen> -backup /D2 /D3 - -backup -V - - - -OS9: backup - -Ready to BACKUP from /D0 to /D1 ?: Y -MYDISK is being scratched -OK ?: Y -Number of sectors copied: $04D0 -Verify pass -Number of sectors verified: $04D0 -OS9: -</screen> -<para> -Below is an example of a single drive backup. BACKUP will read a -portion of the source disk into memory, you remove the source disk -and place the destination disk into the drive, BACKUP writes on the -destination disk, you remove the destination disk and place the -source disk into the drive. This continues until the entire disk -has been copied. Giving BACKUP as much memory as possible will cause -fewer disk exchanges to be required. -</para> -<para> -For more information see: 1.1.2 -</para> -<screen> -OS9:backup /D0 #10k - -Ready to BACKUP from /D0 to /D0 ?: Y -Ready DESTINATION, hit a key: -MYDISK is being scratched -OK ?: Y -Ready SOURCE, hit a key: -Ready DESTINATION, hit a key: -Ready SOURCE, hit a key: -Ready DESTINATION, hit a key: - -(several repetitions) - -Ready DESTINATION, hit a key: -Number of sectors copied: $4D0 -Verify pass -Number of sectors verified: $4D0 -</screen> -</refsect1> -</refentry> - -<refentry id="binex"> -<refnamediv> -<refname id="binexname">BINEX / EXBIN</refname> -<refpurpose>Convert Binary To S-Record File / Convert S-Record To Binary File</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> - <command>BINEX</command> - <arg choice="plain">&replstart;path1&replend;</arg> - <arg choice="plain">&replstart;path2&replend;</arg> -</cmdsynopsis> -<cmdsynopsis> - <command>EXBIN</command> - <arg choice="plain">&replstart;path2&replend;</arg> - <arg choice="plain">&replstart;path1&replend;</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -S-Record files are a type of text file that contains records that -represent binary data in hexadecimal character form. This -Motorola-standard format is often directly accepted by commercial PROM -programmers, emulators, logic analyzers and similar devices that are -interfaced RS-232 interfaces. It can also be useful for -transmitting files over data links that can only handle character-type -data; or to convert OS-9 assembler or compiler-generated -programs to load on non-OS-9 systems. -</para> -<para> -BINEX converts "path1", an OS-9 binary format file, to a new file -named "path2" in S-Record format. If invoked on a non-binary load -module file, a warning message is printed and the user is asked if -BINEX should proceed anyway. A "Y" response means yes; any other -answer will terminate the program. S-Records have a header record -to store the program name for informational purposes and each data -record has an absolute memory address which is not meaningful to OS-9 -since it uses position-independent-code. However, the S-Record -format requires them so BINEX will prompt the user for a program -name and starting load address. For example: -</para> -<screen> -binex /d0/cmds/scanner scanner.S1 -Enter starting address for file: <emphasis>$100</emphasis> -Enter name for header record: <emphasis>scanner</emphasis> -</screen> -<para> -To download the program to a device such as a PROM programmer -(for example using serial port T1) type: -</para> -<screen> -list scanner.S1 >/T1 -</screen> -<para> -EXBIN is the inverse operation; "path1" is assumed to be a -S-Record format text file which EXBIN converts to pure binary form on -a new file called "path2". The load addresses of each data record -must describe continguous data in ascending order. -</para> -<para> -EXBIN does not generate or check for the proper OS-9 module -headers or CRC check value required to actually load the binary -file. The IDENT or VERIFY commands can be used to check the -validity of the modules if they are to be loaded or run. -Example: -</para> -<screen> -exbin program.S1 cmds/program -</screen> -</refsect1> -</refentry> - -<refentry id="build"> -<refnamediv> -<refname id="buildname">BUILD</refname> -<refpurpose>Build a text file from standard input</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>BUILD</command> -<arg choice="plain">&replstart;path&replend;</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to build short text files by copying the -standard input path into the file specified by -&replstart;path&replend;. BUILD creates a file according to the pathlist parameter, -then displays a "?" -prompt to request an input line. Each line entered is written to -the output path (file). Entering a line consisting of a carriage -return only causes BUILD to terminate. -</para> - -</refsect1> -<refsect1><title>Example:</title> - -<screen> -build small_file -build /p (copies keyboard to printer) -</screen> -<para> -The standard input path may also be redirected to a file. Below is -an example: -</para> -<screen> -build <mytext /T2 (copies file "mytext" to terminal T2) - - -OS9: build newfile - -? The powers of the OS-9 -? operating system are truly -? fantastic. -? [RETURN] - -OS9: list newfile - -The powers of the OS-9 -operating system are truly -fantastic. -</screen> -</refsect1> -</refentry> - -<refentry id="chd"> -<refnamediv> -<refname>CHD/CHX</refname> -<refpurpose>Change working data directory / Change working execution directory</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>chd</command> -<arg choice="plain"> - &replstart;pathlist&replend; -</arg> -</cmdsynopsis> -<cmdsynopsis> -<command>chx</command> -<arg choice="plain"> - &replstart;pathlist&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -These are shell "built in" commands used to change OS-9's working -data directory or working execution directory. Many commands in OS-9 -work with user data such as text files, programs, etc. These -commands assume that a file is located in the working data -directory. Other OS-9 commands will assume that a file is in the -working execution directory. -</para> -<para> -NOTE: These commands do not appear in the CMDS directory as they -are built-in to the SHELL. -</para> -<para> -For more information see: 3.7, 3.7.2 - - -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -chd /d1/PROGRAMS - -chx .. - -chx binary_files/test_programs - -chx /D0/CMDS; chd /D1 -</screen> -</refsect1> -</refentry> - -<refentry id="cmp"> -<refnamediv> -<refname>CMP</refname> -<refpurpose>File Comparison Utility</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>cmp</command> -<arg choice="plain"> - &replstart;file1&replend; -</arg> -<arg choice="plain"> - &replstart;file2&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -Opens two files and performs a comparison of the binary values of -the corresponding data bytes of the files. If any differences are -encountered, the file offset (address) and the values of the bytes -from each file are displayed in hexadecimal. -</para> -<para> -The comparison ends when end-of-file is encountered on either -file. A summary of the number of bytes compared and the number of -differences found is then displayed. -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> - -OS9: cmp red blue - - Differences - -byte #1 #2 -======== == == -00000013 00 01 -00000022 B0 B1 -0000002A 9B AB -0000002B 3B 36 -0000002C 6D 65 - -Bytes compared: 0000002D -Bytes different: 00000005 - -OS9: cmp red red - - Differences - None ... - -Bytes compared: 0000002D -Bytes different: 00000000 -</screen> -</refsect1> -</refentry> - -<refentry id="cobbler"> -<refnamediv> -<refname>COBBLER</refname> -<refpurpose>Make a bootstrap file</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>COBBLER</command> -<arg choice="plain"> - &replstart;device name&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -COBBLER is used to create the "OS9Boot" file required on any disk -from which OS-9 is to be bootstrapped. The boot file will consist -of the <emphasis>same modules which were loaded into memory during the most -recent boostrap.</emphasis> -To add modules to the bootstrap file use the -"OS9Gen" command. COBBLER also writes the OS-9 kernel on the first -fifteen sectors of track 34, and excludes these sectors from the -disk allocation map. If any files are present on these sectors -COBBLER will display an error message. -</para> -<para> -NOTE: The boot file must fit into one contiguous block on the mass-storage -device. For this reason COBBLER is normally used on a -freshly formatted disk. If COBBLER is used on a disk and there is -not a contiguous block of storage large enough to hold the boot -file, the old boot file may have been destroyed and OS-9 will not be -able to boot from that disk until it is reformatted. -</para> -<para> -For more information see: 1.1.2, 6.1 -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -OS9: cobbler /D1 -</screen> -</refsect1> -</refentry> - -<refentry id="copy"> -<refnamediv> -<refname>COPY</refname> -<refpurpose>Copy data from one path to another</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>COPY</command> -<arg choice="plain"> - &replstart;path&replend; -</arg> -<arg choice="plain"> - &replstart;path&replend; -</arg> -<arg choice="opt"> - <option>-s</option> -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command copies data from the first file or device specified to -the second. The first file or device must already exist, the -second file is automatically created if the second path is a file on -a mass storage device. Data may be of any type and is NOT modified -in any way as it is copied. -</para> -<para> -Data is transferred using large block reads and writes until end-of-file -occurs on the input path. Because block transfers are used, -normal output processing of data does not occur on character-oriented -devices such as terminals, printers, etc. Therefore, the -LIST command is preferred over COPY when a file consisting of text -is to be sent to a terminal or printer. -</para> -<para> -The "-s" option causes COPY to perform a single drive copy -operation. The second pathlist must be a full pathlist if "-s -appears. COPY will read a portion of the source disk into memory, -you remove the source disk and place the destination disk into the -drive, enter a "C" whereupon COPY writes on the destination disk, -this process continues until the entire file is copied. -</para> -<para> -Using the shell's alternate memory size modifier to give a large -memory space will increase speed and reduce the number of media -exchanges required for single drive copies. -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -copy file1 file2 #15k (copies file1 to file2) - -copy /D1/joe/news /D0/peter/messages - -copy /TERM /P (copies console to printer) - -copy /d0/cat /d0/animals/cat -s #32k -Ready DESTINATION, hit C to continue: c -Ready SOURCE, hit C to continue: c -Ready DESTINATION, hit C to continue:c -</screen> -</refsect1> -</refentry> - -<refentry id="date"> -<refnamediv> -<refname>DATE</refname> -<refpurpose>Display system date and time</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DATE</command> -<arg choice="opt"> - <option>t</option> -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command will display the current system date, and if the "t" -option is given, the current system time. -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -date t - -date t >/p (Output is redirected to printer) - -OS9: setime - - YY/MM/DD HH:MM:SS -TIME ? 81/04/15 14:19:00 - -OS9:date - -April 15, 1981 - -OS9:date t - -April 15, 1981 14:20:20 -</screen> -</refsect1> -</refentry> - -<refentry id="dcheck"> -<refnamediv> -<refname>DCHECK</refname> -<refpurpose>Check Disk File Structure</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DCHECK</command> -<arg choice="opt"> - <option>-opts</option> -</arg> -<arg choice="plain"> - &replstart;devnam&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -It is possible for sectors on a disk to be marked as being allocated -but in fact are not actually associated with a file or the disk's -free space. This can happen if a disk is removed from a drive while -files are still open, or if a directory which still contains files -is deleted (see 3.5). DCHECK is a diagnostic that can be used to -detect this condition, as well as the general integrity of the directory/file linkages. -</para> -<para> -DCHECK is given as a parameter the name of the disk device to be -checked. After verifying and printing some vital file structure -parameters, DCHECK follows pointers down the disk's file system tree -to all directories and files on the disk. As it does so, it -verifies the integrity of the file descriptor sectors, reports any -discrepancies in the directory/file linkages, and builds a sector -allocation map from the segment list associated with each file. If -any file descriptor sectors (FDs) describe a segment with a cluster -not within the file structure of the disk, a message is reported -like: -</para> -<screen> -*** Bad FD segment ($xxxxxx-$yyyyyy) for file: &replstart;pathlist&replend; -</screen> -<para> -This indicates that a segment starting at sector xxxxxx and ending -at sector yyyyyy cannot really be on this disk. Because there is a -good chance the entire FD is bad if any of it's segment descriptors -are bad, the allocation map is <emphasis>not</emphasis> updated for corrupt FDs. -</para> -<para> -While building the allocation map, DCHECK also makes sure that each -disk cluster appears only once and only once in the file structure. -If this condition is detected, DCHECK will display a message like: -</para> -<screen> -Cluster $xxxxxx was previously allocated -</screen> -<para> -This message indicates that cluster xxxxxx has been found at least -once before in the file structure. The message may be printed more -than once if a cluster appears in a segment in more than one file. -</para> -<para> -The newly created allocation map is then compared to the allocation -map stored on the disk, and any differences are reported in messages -like: -</para> -<screen> -Cluster $xxxxxx in allocation map but not in file structure -Cluster $xxxxxx in file structure but not in allocation map -</screen> -<para> -The first message indicates sector number xxxxxx (hexadecimal) was -found not to be part of the file system, but was marked as allocated -in the disk's allocation map. In addition to the causes mentioned -in the first paragraph, some sectors may have been excluded from the -allocation map by the FORMAT program because they were defective or -they may be the last few sectors of the disk, the sum of which was -two small to comprise a cluster. -</para> -<para> -The second message indicates that the cluster starting at sector -xxxxxx is part of the file structure but is <emphasis>not</emphasis> -marked as allocated -in the disk's allocation map. It is possible that this cluster may -be allocated to another file later, overwriting the contents of the -cluster with data from the newly allocated file. Any clusters that -have been reported as "previously allocated" by DCHECK as described -above surely have this problem. -</para> -<para> -Available DCHECK options are: -</para> - -<informaltable frame="none"> -<tgroup cols="2"> -<colspec colwidth="1.3in"> -<colspec colwidth="3in"> -<tbody> -<row> -<entry>-w=&replstart;path&replend;</entry> -<entry>pathlist to directory for work files</entry> -</row> -<row> -<entry>-p</entry> -<entry>print pathlists for questionable clusters</entry> -</row> -<row> -<entry>-m</entry> -<entry>save allocation map work files</entry> -</row> -<row> -<entry>-b</entry> -<entry>suppress listing of unused clusters</entry> -</row> -<row> -<entry>-s</entry> -<entry>display count of files and directories only</entry> -</row> -<row> -<entry>-o</entry> -<entry>print DCHECK's valid options</entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The "-s" option causes DCHECK to display a count of files and -directories only; only FDs are checked for validity. The "-b" option -suppresses listing of clusters allocated but not in file structure. -The "-p" option causes DCHECK to make a second pass through the file -structure printing the pathlists for any clusters that DCHECK finds -as "already allocated" or "in file structure but not in allocation -map". The "-w=" option tells DCHECK where to locate it's allocation -map work file(s). The pathlist specified must be a FULL pathlist to -a <emphasis>directory</emphasis>. The directory "/D0" is -used is used if "-w" is not -specified. It is recommended that this pathlist NOT be located on -the disk being DCHECKed if the disk's file structure integrity is in -doubt. -</para> -<para> -DCHECK builds its disk allocation map in a file called -&replstart;pathlist&replend;/DCHECKppO, where &replstart;pathlist&replend; -is as specified by the -"-w=" option and pp is the process number in hexadecimal. Each bit -in this bitmap file corresponds to a cluster of sectors on the disk. -If the "-p" option appears on the command line, DCHECK creates a -second bitmap file (&replstart;pathlist&replend;/DCHECKpp1) that has a bit set for -each cluster DCHECK finds as "previously allocated" or "in file -structure but not in allocation map" while building the allocation -map. DCHECK them makes another pass through the directory structure -to determine the pathlists for these questionable clusters. These -bitmap work files may be saved by specifying the "-m" option on the -command line. -</para> -</refsect1> -<refsect1><title>Restrictions</title> -<para> -For best results, DCHECK should have exclusive access to the disk -being checked. Otherwise DCHECK may be fooled if the disk allocation map -changes while it is building its bitmap file from the -changing file structure. DCHECK cannot process disks with a directory -depth greater than 39 levels. -</para> -<para> -For more information see: 3.10, 3.5, FORMAT, - 6.1 of OS-9 Systems Programmer's Manual -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -OS9: dcheck /d2 (workfile is on /D0) - -Volume - 'My system disk' on device /d2 -$009A bytes in allocation map -1 sector per cluster -$0004D0 total sectors on media -Sector $000002 is start of root directory FD -$0010 sectors used for id, allocation map and root directory -Building allocation map work file... -Checking allocation map file... - - -'My system disk' file structure is intact -1 directory -2 files - -OS9: dcheck -mpw=/d2 /d0 -Volume - 'System disk' on device /d0 -$0046 bytes in allocation map -1 sector per cluster -$00022A total sectors on media -Sector $000002 is start of root directory FD -$0010 sectors used for id, allocation map and root directory -Building allocation map work file... -Cluster $00040 was previously allocated -*** Bad FD segment ($111111-$23A6F0) for file: /d0/test/junky.file -Checking allocation map file... -Cluster $000038 in file structure but not in allocation map -Cluster $00003B in file structure but not in allocation map -Cluster $0001B9 in allocation map but not in file structure -Cluster $0001BB in allocation map but not in file structure - -Pathlists for questionable clusters: -Cluster $000038 in path: /d0/OS9boot -Cluster $00003B in path: /d0/OS9boot -Cluster $000040 in path: /d0/OS9boot -Cluster $000040 in path: /d0/test/double.file - -1 previously allocated clusters found -2 clusters in file structure but not in allocation map -2 clusters in allocation map but not in file structure -1 bad file descriptor sector - -'System disk' file structure is not intact -5 directories -25 files -</screen> -</refsect1> -</refentry> - -<refentry id="del"> -<refnamediv> -<refname>DEL</refname> -<refpurpose>Delete a file</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DEL</command> -<arg choice="opt"> - <option>-x</option> -</arg> -<arg choice="plain"> - &replstart;path&replend; -</arg> -<arg choice="plain"> - &repeatst;&replstart;path&replend;&repeaten; -</arg> -<arg choice="opt"> - <option>-x</option> -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to delete the file(s) specified by the -pathllst(s). The user must have write permission for the file(s). -Directory files cannot be deleted unless their type is changed to -non-directory: see the "ATTR" command description. -</para> -<para> -If the -x option appears, the current -<emphasis>execution</emphasis> directory is assumed. -</para> -<para> -For more information see: 3.5, 3.8.1 -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -del test_program old_test_program - -del /D1/number_five - -OS9:dir /D1 - - Directory of /D1 14:29:46 -myfile newfile - -OS9:del /D1/newfile -OS9:dir /D1 - - Directory of /D1 14:30:37 -myfile - -OS9:del myprog -x -OS9:del -x CMDS.SUBDIR/file -</screen> -</refsect1> -</refentry> - -<refentry id="deldir"> -<refnamediv> -<refname>DELDIR</refname> -<refpurpose>Delete All Files In a Directory System</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DELDIR</command> -<arg choice="plain"> - &replstart;directory name&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is a convenient alternative to manually deleting -directories and files they contain. It is only used when -<emphasis>all</emphasis> files in the directory system are to be deleted. -</para> -<para> -When DELDIR is run, it prints a prompt message like this: -</para> -<screen> -OS9: deldir OLDFILES -Deleting directory file. -List directory, delete directory, or quit ? (l/d/q) -</screen> -<para> -An "l" response will cause a "dir e" command to be run so you can -have an opportunity to see the files in the directory before they -are deleted. -</para> -<para> -A "d" response will initiate the process of deleting files. -</para> -<para> -A "q" response will abort the command before action is taken. -</para> -<para> -The directory to be deleted may include directory files, which -may themselves include directory files, etc. In this case, DELDIR -operates recursively (e.g., it calls itself) so all lower-level -directories are deleted as well. In this case the lower-level -directories are processed first. -</para> -<para> -You must have correct access permission to delete all files and -directories encountered. If not, DELDIR will abort upon -encountering the first file for which you do not have write -permission. -</para> -<para> -The DELDIR command automatically calls the DIR and ATTR -commands, so they both must reside in the current execution -directory. -</para> -</refsect1> -</refentry> - -<refentry id="dir"> -<refnamediv> -<refname>DIR</refname> -<refpurpose>Display the names of files contained in a directory</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DIR</command> -<arg choice="opt"> - <option>e</option> -</arg> -<arg choice="opt"> - <option>x</option> -</arg> -<arg choice="opt"> - &replstart;path&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -Displays a formatted list of files names in a directory file on. the -standard output path. If no parameters are given, the current -<emphasis>data</emphasis> -directory is shown. If the "x" option is given, the current -<emphasis>execution</emphasis> -directory is shown. If a pathlist of a directory file is -given, it is shown. - -</para> -<para> -If the "e" option is included, each file's entire description is -displayed: size, address, owner, permissions, date and time of last -modification. - -</para> -<para> -For more information see: 1.0.3, 3.4, and 3.8.1 -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -dir (display data directory) - -dir x (display execution directory) - -dir x e (display entire description of execution dir) - -dir .. (display parent of working data directory) - -dir newstuff (display newstuff directory) - -dir e test_programs (display entire description of "test.programs) -</screen> -</refsect1> -</refentry> - -<refentry id="display"> -<refnamediv> -<refname>DISPLAY</refname> -<refpurpose>Display Converted Characters</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DISPLAY</command> -<arg choice="plain"> - &replstart;hex&replend; -</arg> -<arg choice="plain"> - &repeatst;&replstart;hex&replend;&repeaten; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -Display reads one or more hexadecimal numbers given as parameters, -converts them to ASCII characters, and writes them to the standard -output. It is commonly used to send special characters (such as -cursor and screen control codes) to terminals and other I/O devices. - -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -display 0C 1F 02 7F - - -display 15 >/p (sends "form feed" to printer) - -OS9: display 41 42 43 44 45 46 -ABCDEF -</screen> -</refsect1> -</refentry> - -<refentry id="dsave"> -<refnamediv> -<refname>DSAVE</refname> -<refpurpose>Generate procedure file to copy files</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>DSAVE</command> -<arg choice="opt"> - <option>-opts</option> -</arg> -<arg choice="opt"> - &replstart;devname&replend; -</arg> -<arg choice="opt"> - &replstart;path&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -Dsave is used to backup or copy all files in one or more -directories. It is unlike most other commands in that it does NOT -directly affect the system, rather, it generates a procedure file -which is executed later to actually do the work. -</para> -<para> -When DSAVE is executed, it writes copy commands to -<emphasis>standard output</emphasis> -to copy files from the current <emphasis>data</emphasis> directory -on &replstart;devname&replend; (the default is /D0) to the directory -specified by &replstart;path&replend;. If &replstart;path&replend; -does not appear, the copy is performed to the current data directory -<emphasis>at the time the DSAVE procedure file is executed.</emphasis> -If DSAVE -encounters a directory file, it will automatically include "makdir" -and "chd" commands in the output before generating copy commands for -files in the subdirectory. Since DSAVE is recursive in operation, -the procedure file will exactly replicate all levels of the file -system from the current data directory downward (such a section of -the file system is called a "subtree"). -</para> -<para> -If the current working directory happens to be the root directory of -the disk, DSAVE will create a procedure file that will backup the -entire disk file by file. This is useful when it is necessary to -copy many files from different format disks, or from floppy disk to -a hard disk. -</para> -<para> -Available DSAVE options are: -</para> - -<informaltable frame="none"> -<tgroup cols="2"> -<colspec colwidth="1in"> -<colspec colwidth="4in"> -<tbody> -<row> -<entry>-b</entry> -<entry>make output disk a system disk by using source disk's -"OS9Boot" file,. if present.</entry> -</row> -<row> -<entry>-b=&replstart;path&replend;</entry> -<entry>make output disk a system disk using &replstart;path&replend; as source -for the "OS9Boot" file.</entry> -</row> -<row> -<entry>-i</entry> -<entry>indent for directory levels</entry> -</row> -<row> -<entry>-L</entry> -<entry>do not process directories below the current level</entry> -</row> -<row> -<entry>-m</entry> -<entry>do not include "makdir" commands in procedure file</entry> -</row> -<row> -<entry>-s&replstart;integer&replend;</entry> -<entry>set copy size parameter to &replstart;integer&replend; K</entry> -</row> -</tbody> -</tgroup> -</informaltable> - - -<para> -For more information see: 1.1.3 -</para> -</refsect1> -<refsect1><title>Examples</title> -<para> -Example which copies all files on "d2" to "d1": -</para> -<screen> -chd /d2 (select "from" directory) -dsave /d2 >/d0/makecopy (make procedure file "makecopy") -chd /d1 (select "to" directory) -/d0/makcopy (run procedure file) - -chd /d0/MYFILES/STUFF -dsave -is32 /d0 /d1/BACKUP/STUFF >saver -/d0/MYFILES/STUFF/saver -</screen> -</refsect1> -</refentry> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<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> - -<refentry id="tmode"> -<refnamediv> -<refname>TMODE</refname> -<refpurpose>Change terminal operating mode</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>TMODE</command> -<arg choice="opt"> - .&replstart;pathnum&replend; -</arg> -<arg choice="opt"> - &replstart;arglist&replend; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to display or change the operating parameters -of the user's terminal. -</para> -<para> -If no arguments are given, the present values for each parameter are -displayed, otherwise, the parameter(s) given in the argument list -are processed. Any number of parameters can be. given, and are -separated by spaces or commas. A period and a number can be used to -optionally specify the path number to be affected. If none is given, -the standard input path is affected. -</para> -<para> -NOTE: If this command is used in a shell procedure file, the -option ".&replstart;path num&replend;" must be used to specify one of the standard -output paths (0, 1 or 2) to change the terminal's operating -characteristics. The change will remain in effect until the path is -closed. To effect a permanent change to a device characteristic, -the device descriptor must be changed. -</para> -<para> -This command can work only if a path to the file/device has already -been opened. You may alter the device descriptor to set a device's -initial operating parameter (see the System Programmer's Manual). -</para> - -<informaltable frame="none"> -<tgroup cols="2"> -<colspec colwidth="1in"> -<colspec colwidth="4in"> -<tbody> -<row> -<entry>upc</entry> -<entry>Upper case only. Lower case characters are automatically -converted to upper case.</entry> -</row> -<row> -<entry>-upc</entry> -<entry>Upper case and lower case characters permitted (default).</entry> -</row> -<row> -<entry>bsb</entry> -<entry>Erase on backspace: backspace characters echoed as a -backspace-space-backspace sequence (default).</entry> -</row> -<row> -<entry>-bsb</entry> -<entry>no erase on backspace: echoes single backspace only</entry> -</row> -<row> -<entry>bsl</entry> -<entry>Backspace over line: lines are "deleted" by sending -backspace-space-backspace sequences to erase the same -line (for video terminals) (default).</entry> -</row> -<row> -<entry>-bsl</entry> -<entry>No backspace over line: lines are "deleted" by printing -a new line sequence (for hard-copy terminals). -echo Input characters "echoed" back to terminal (default)</entry> -</row> -<row> -<entry>-echo</entry> -<entry>No echo</entry> -</row> -<row> -<entry>lf</entry> -<entry>Auto line feed on: line feeds automatically echoed to -terminal on input and output carriage returns (default).</entry> -</row> -<row> -<entry>-lf</entry> -<entry>Auto line feed off.</entry> -</row> -<row> -<entry>pause</entry> -<entry>Screen pause on: output suspended upon full screen. See -"pag" parameter for definition of screen size. Output -can be resumed by typing any key.</entry> -</row> -<row> -<entry>-pause</entry> -<entry>Screen pause mode off.</entry> -</row> -<row> -<entry>null=n</entry> -<entry>Set null count: number of null ($00) characters -transmitted after carriage returns for return delay. -The number is decimal, default = 0.</entry> -</row> -<row> -<entry>pag=n</entry> -<entry>Set video display page length to n (decimal) lines. -Used for "pause" mode, see above.</entry> -</row> -<row> -<entry>bsp=h</entry> -<entry>Set input backspace character. Numeric value of -character in hexadecimal. Default = 08.</entry> -</row> -<row> -<entry>bse=h</entry> -<entry>Set output backspace character. Numeric value of -character in hexadecimal. Default = 08.</entry> -</row> -<row> -<entry>del=h</entry> -<entry>Set input delete line character. Numeric value of -character in hexadecimal. Default = 18.</entry> -</row> -<row> -<entry>bell=h</entry> -<entry>Set bell (alert) output character. Numeric value of -character in hexadecimal. Default = 07</entry> -</row> -<row> -<entry>eor=h</entry> -<entry>Set end-of-record (carriage return) input character. -Numeric value of character in hexadecimal. Default = 0D</entry> -</row> -<row> -<entry>eof=h</entry> -<entry>Set end-of-file input character. Numeric value of -character in hexadecimal. Default 1B.</entry> -</row> -<row> -<entry>type=h</entry> -<entry>ACIA initialization value: sets parity, word size, etc. -Value in hexadecimal. Default 15</entry> -</row> -<row> -<entry>reprint=h</entry> -<entry>Reprint line character. Numeric value of character -in hexadecimal.</entry> -</row> -<row> -<entry>dup=h</entry> -<entry>Duplicate last input line character. Numeric value of -character in hexadecimal.</entry> -</row> -<row> -<entry>psc=h</entry> -<entry>Pause character. Numeric value of character in -hexadecimal.</entry> -</row> -<row> -<entry>abort=h</entry> -<entry>Abort character (normally control C). Numeric value -of character in hexadecimal.</entry> -</row> -<row> -<entry>quit=h</entry> -<entry>Quit character (normally control E). Numeric value -of character in hexadecimal.</entry> -</row> -<row> -<entry>baud=d</entry> -<entry>Set baud rate for software-controllable interface. Numeric -code for baud rate: 0=110 1=300 2=600 3=1200 4=2400 5=4800 -6=9600 7=19200</entry> -</row> -</tbody> -</tgroup> -</informaltable> - -</refsect1> -<refsect1><title>Examples</title> -<screen> -tmode -upc lf null=4 bselF pause - -tmode pag=24 pause bsl -echo bsp=8 bsl=C -</screen> -<para> -NOTE: If you use TMODE in a procedure file, it will be necessary to -specify one of the standard output paths (.1 or .2) since the -shell's standard input path will have been redirected to the disk -file (TMODE can be used on an SCFMAN-type devices only). - -Example: -</para> -<screen> -tmode .1 pag=24 (set lines/page on standard output) -</screen> -</refsect1> -</refentry> - -<refentry id="tsmon"> -<refnamediv> -<refname>TSMON</refname> -<refpurpose>Timesharing monitor</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>TSMON</command> -<arg choice="opt">&replstart;pathlist&replend;</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to supervise idle terminals and initiate the -login sequence in timesharing applications. If a pathlist is given, -standard I/O paths are opened for the device. When a carriage return -is typed, TSMON will automatically call the "LOGIN" command. If the -login fails because the user could not supply a valid user name or -password, it will return to TSMON. -</para> -<para> -Note: The LOGIN command and its password file must be present for -TSMON to work correctly (see the LOGIN command description). -</para> -<refsect2> -<title>Logging Off the System</title> -<para> -Most programs will terminate when an end of file character (escape) -is entered as the first character on a command line. This will log -you off of the system and return control to TSMON. -</para> -<para> -For more information see: 2.5, LOGIN -</para> -</refsect2> -</refsect1> -<refsect1><title>Examples</title> -<screen> - -OS9:tsmon /t1& -&005 -</screen> -</refsect1> -</refentry> - -<refentry id="unlink"> -<refnamediv> -<refname>UNLINK</refname> -<refpurpose>Unlink memory module</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>UNLINK</command> -<arg choice="plain"> - &replstart;modname&replend; -</arg> -<arg choice="plain"> -&repeatst; &replstart;modname&replend;&repeaten; -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -Tells OS-9 that the memory module(s) named are no longer needed by -the user. The module(s) may or may not be destroyed and their -memory reassigned, depending on if in use by other processes or -user, whether resident in ROM or RAM, etc. -</para> -<para> -It is good practice to unload modules whenever possible to make most -efficient use of available memory resources. -</para> -<para> - -Warning: never unlink a module you did not load or link to. -</para> -<para> - - -For more information see: 5.4, 5.4.1, 5.4.2 -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -unlink pgml pgm5 pgm99 - - -OS9: mdir - - Module Directory at 11:26:22 -DCB4 D0 D1 D2 D3 -OS9P2 INIT OS9 IOMAN RBF -SCF ACIA TERM T1 T2 -T3 P PIA Sysgo Clock -Shell Tsmon Edit - -OS9: unlink edit -OS9: mdir - - Module Directory at 11:26:22 -DCB4 D0 D1 D2 D3 -OS9P2 INIT OS9 IOMAN RBF -SCF ACIA TERM T1 T2 -T3 P PIA Sysgo Clock -Shell Tsmon -</screen> -</refsect1> -</refentry> - -<refentry id="verify"> -<refnamediv> -<refname>VERIFY</refname> -<refpurpose>Verify or update module header and CRC</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>VERIFY</command> -<arg choice="opt"> - <option>u</option> -</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> - -<para> -This command is used to verify that module header parity and CRC -value of one or more modules on a file (standard input) are correct. -Module(s) are read from standard input, and messages will be sent to -the standard error path. -</para> -<para> -If the U (update) option is specified, the module(s) will be copied -to the standard output path with the module's header parity and CRC -values replaced with the computed values. A message will be -displayed to indicate whether or not the module's values matched -those computed by VERIFY. -</para> -<para> -If the option is NOT specified, the module will not be copied to -standard output. VERIFY will only display a message to indicate -whether or not the module's header parity and CRC matched those -which were computed. -</para> -</refsect1> -<refsect1><title>Examples</title> -<screen> -OS9: verify <EDIT >NEWEDIT - -Module's header parity is correct. -Calculated CRC matches module's. - -OS9: verify <myprograml >myprogram2 - -Module's header parity is correct. -CRC does not match. - -OS9: verify <myprogram2 - -Module's header parity is correct. -Calculated CRC matches module's. - -OS9: verify u <module >temp -</screen> -</refsect1> -</refentry> - -<refentry id="xmode"> -<refnamediv> -<refname>XMODE</refname> -<refpurpose>Examine or Change Device Initialization Mode</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<cmdsynopsis> -<command>XMODE</command> -<arg choice="plain">&replstart;devname&replend;</arg> -<arg choice="opt">&replstart;arglist&replend;</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> -<para> -This command is used to display or change the initialization -parameters of any SCF-type device such as the video display, -printer, RS232 port, etc. A common use is to change baud rates, -control key definitions, etc. -</para> -<para> -XMODE is very similar to the TMODE command. TMODE only operates on -open paths so its effect is temporary. XMODE actually updates the -device descriptor so the change persists as long as the computer is -running, even if paths to the device are repetitively opened and -closed. If XMODE is used to change parameter(s) and the COBBLER -program is used to make a new system disk, the changed parameter -will be permanently reflected on the new system disk. -</para> -<para> -XMODE requires a device name to be given. If no arguments are -given, the present values for each parameter are displayed, -otherwise, the parameter(s) given in the argument list are -processed. Any number of parameters can be given, and are separated -by spaces or commas. -</para> - -</refsect1> -<refsect1><title>XMODE Parameter Names</title> - -<informaltable frame="none"> -<tgroup cols="2"> -<colspec colwidth="1in"> -<colspec colwidth="4in"> -<tbody> -<row> -<entry>upc</entry> -<entry>Upper case only. Lower case characters are automatically -converted to upper case.</entry> -</row> -<row> -<entry>-upc</entry> -<entry>Upper case and lower case characters permitted (default).</entry> -</row> -<row> -<entry>bsb</entry> -<entry>Erase on backspace: backspace characters echoed as a -backspace-space-backspace sequence (default).</entry> -</row> -<row> -<entry>-bsb</entry> -<entry>no erase on backspace: echoes single backspace only</entry> -</row> -<row> -<entry>bsl</entry> -<entry>Backspace over line: lines are "deleted" by sending -backspace-space-backspace sequences to erase the same -line (for video terminals) (default).</entry> -</row> -<row> -<entry>-bsl</entry> -<entry>No backspace over line: lines are "deleted" by printing -a new line sequence (for hard-copy terminals). -echo Input characters "echoed" back to terminal (default)</entry> -</row> -<row> -<entry>-echo</entry> -<entry>No echo</entry> -</row> -<row> -<entry>lf</entry> -<entry>Auto line feed on: line feeds automatically echoed to -terminal on input and output carriage returns (default).</entry> -</row> -<row> -<entry>-lf</entry> -<entry>Auto line feed off.</entry> -</row> -<row> -<entry>pause</entry> -<entry>Screen pause on: output suspended upon full screen. See -"pag" parameter for definition of screen size. Output -can be resumed by typing any key.</entry> -</row> -<row> -<entry>-pause</entry> -<entry>Screen pause mode off.</entry> -</row> -<row> -<entry>null=n</entry> -<entry>Set null count: number of null ($00) characters -transmitted after carriage returns for return delay. -The number is decimal, default = 0.</entry> -</row> -<row> -<entry>pag=n</entry> -<entry>Set video display page length to n (decimal) lines. -Used for "pause" mode, see above.</entry> -</row> -<row> -<entry>bsp=h</entry> -<entry>Set input backspace character. Numeric value of -character in hexadecimal. Default = 08.</entry> -</row> -<row> -<entry>bse=h</entry> -<entry>Set output backspace character. Numeric value of -character in hexadecimal. Default = 08.</entry> -</row> -<row> -<entry>del=h</entry> -<entry>Set input delete line character. Numeric value of -character in hexadecimal. Default = 18.</entry> -</row> -<row> -<entry>bell=h</entry> -<entry>Set bell (alert) output character. Numeric value of -character in hexadecimal. Default = 07</entry> -</row> -<row> -<entry>eor=h</entry> -<entry>Set end-of-record (carriage return) input character. -Numeric value of character in hexadecimal. Default = 0D</entry> -</row> -<row> -<entry>eof=h</entry> -<entry>Set end-of-file input character. Numeric value of -character in hexadecimal. Default 1B.</entry> -</row> -<row> -<entry>type=h</entry> -<entry>ACIA initialization value: sets parity, word size, etc. -Value in hexadecimal. Default 15</entry> -</row> -<row> -<entry>reprint=h</entry> -<entry>Reprint line character. Numeric value of character -in hexadecimal.</entry> -</row> -<row> -<entry>dup=h</entry> -<entry>Duplicate last input line character. Numeric value of -character in hexadecimal.</entry> -</row> -<row> -<entry>psc=h</entry> -<entry>Pause character. Numeric value of character in -hexadecimal.</entry> -</row> -<row> -<entry>abort=h</entry> -<entry>Abort character (normally control C). Numeric value -of character in hexadecimal.</entry> -</row> -<row> -<entry>quit=h</entry> -<entry>Quit character (normally control E). Numeric value -of character in hexadecimal.</entry> -</row> -<row> -<entry>baud=d</entry> -<entry>Set baud rate for software-controllable interface. Numeric -code for baud rate: 0=110 1=300 2=600 3=1200 4=2400 5=4800 -6=9600 7=19200</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</refsect1> -<refsect1><title>Examples</title> -<screen> -xmode /TERM -upc lf null=4 bse=1F pause - -xmode /T1 pag=24 pause bsl -echo bsp=8 bsl=C - -xmode /P baud=3 -if -</screen> -</refsect1> -</refentry> +&attrref; +&backupref; +&binexref; +&buildref; +&chdref; +&cmpref; +&cobblerref; +©ref; +&dateref; +&dcheckref; +&delref; +&deldirref; +&dirref; +&displayref; +&dsaveref; +&dumpref; +&echoref; +&exref; +&formatref; +&freeref; +&identref; +&killref; +&linkref; +&listref; +&loadref; +&loginref; +&makdirref; +&mdirref; +&mergeref; +&mfreeref; +&os9genref; +&printerrref; +&procsref; +&pwdref; +&renameref; +&saveref; +&setimeref; +&setprref; +&shellref; +&sleepref; +&teeref; +&tmoderef; +&tsmonref; +&unlinkref; +&verifyref; +&xmoderef; </section> </chapter>