Manx Aztec C 6502 for Apple II ProDOS
Alphabetical (more or less) Utility Commands
/* Apple // and UNIX function */ or /* Apple // and UNIX utility */The contact information in the release notes for the electronic manual is as follows, but Manx Software Systems have apparently since faded from existence:
arcv arcfile /* Apple // Utility */ mkarcv arcfileDESCRIPTION
arcv extracts the source from the archive arcfile, which has been prevously created be mkarcv, placing the results in seperated files in the current directory. mkarcv creates the archive file arcfile, placing it in the files whose names it reads from its standard input. Only on file name is read from a standard input line.EXAMPLE
For example, the file header.arc contains the source for all the header files. To create these header files, enter: arcv header.arc The files will be created in the current directory. The following command creates the archive myarc.arc containing the file in.c, out.c, and hello.c: mkarcv myarc < myarc.bld The names of the three files are contained in the file myarc.bld: in.c out.c hello.cBUGS
It's not possible to archive whole subdirectories and arcv can't find files with the complete pathname (that means the files for the archive have to be in the current directory).<< Back to Top
as [-options] prog.asm /* Apple // ProDOS utility */ asi [-options] prog.asm The 6502 assembler is named as on native versions of Aztec C65 and as65 on cross development versions. Relocatable object files are named .r on the MS-DOS cross development version of Aztec C65.DESCRIPTION
as and asi are relocating assemblers that translate an assembly language source program into relocatable object code. The two assemblers support different machines: as accepts assembly language for a 6502 or 65C02; asi accepts assembly language for a "pseudo machine". In an executable program, an asi-assembled module must be interpreted by a routine that is in the Aztec libraries. An executable program can contain both modules that have been assembled with as and modules that have been assembled with asi. This description has three sections: the first describes how to operate the assembler; the second describes the assembler's options; and the third presents information of interest to those writing assembly language programs. 1. OPERATING INSTRUCTIONS Operationally, the two assemblers are very similar. In the following paragraphs, we will use the name as when referring to features that are common to both assemblers. When the two assemblers differ, we will say so. as is started with a command line of the form as [-options] prog.asm where [-options] are optionally parameters and prog.asm is the name of the file to be assembled. as reads the source code from the specified file, translates it into object code, and writes the object code to another file. 1.1 The Source File The extension on the source file name is optional. If not specified, it's assumed to be .asm . For example, with the following command, the assembler will assume that the file is test.asm: as test as will append .asm to the source file name only if it doesn't find a period in the file name. So if the name of the source file really doesn't have an extension, you must assemble it like this: as filename. The period tells the assembler not to append .asm to the name. 1.2 The Object File By default, the name of the file to which as writes object code is derived from the name of the source code file, by changing its extension to .o (or to .i, if asi is used). Also by default, the object code file is placed in the directory that contains the source code file. For example, the command as test.asm writes object code to the file test.o (or to test.i, if asi is used), placing this file in the current directory. You can explicitly specify the name of the object code file, using the -O option. The name of the object code file follows the -O, with spaces between the -O and the file name. For example, the following command assembles test.asm, writing the object code to the file prog.out: as -o prog.out test.asm 1.3 The Listing File The -L option causes the assembler to create a file containing a listing of the program beeing assembled. The file is placed in the directory that contains the object file; its derived from that of the object file by changing the extension to .lst . 1.4 Searching for instxt files The instxt directive tells as to suspend assembly of one file and assemble another; when assembly of the second file is completed, assembly of the first continues. You can make the assembler search for instxt file in a sequence of directories, thus allowing source files and instxt files to be in different directories. Directories that are to be searched are defined just as for the compilers; that is, using the -I assembler option or the INCLUDE environment variable. Optionally, the compiler can also serach the current directory. Directory search for a particular instxt directive can be disabled by specifying a directory name in the directive. In this case, just the specified directory is searched. 1.4.1 The -I option A -I option defines a single directory to be searched. The directory name follows the -I, with no intervening blanks. For example, the following -I option tells the assembler to search the include directory on the ram volume: -I/ram/include 1.4.2 The INCLUDE environment variable The INCLUDE environment variable defines a directory to be searched for instxt files. The example sets INCLUDE so that the assembler will search for instxt files in the directory /ram/include : set INCLUDE=/ram/include 1.4.3 The search order Directories are searched in the following order: 1. If the instxt directive delimited the file name with the double quote character, ", the current directory on the default drive is searched. If delimited by angle brackets, < and >, this directory isn't automatically searched. 2. The directories defined in -I option are searched, in the order listed on the command line. 3. The directory defined in the INCLUDE environment varibale is searched. 2. ASSEMBLER OPTIONS The assembler supports the following options: Option Meaning -O objname Send object code to objname. -L Generate listing. -C Disable assembly of 65C02 instructions. Not supported by asi. -ZAP Delete the source file after assembling it. 3. PROGRAMMING INFORMATION This section discusses the assembly language that is supported by as. A description of the assembly language supported by asi is not available. as supports the standard MOS Technology syntax: a program consist of sequence of statements, each of which is in the standard MOS Tech form; and the assembler supports the MOS Tech mnemonics for the standard instructions. as supports some of the MOS Tech directives and their mnemonics; it also supports others, as defined below. The following paragraphs define in more detail the language supported by as. 3.1 Statement Syntax [label] [opcode] [arguments] [[;]comment] where the brackets "[...]" indicate an optional element. 3.2 Labels A statement's label field defines a symbol to the assembler and assigns it a value. If present, the symbol name begins in column one. If a statement is not labeled, then column one must be blank, tab, or asterisk. An asterisk denotes a comment line. Normally, the symbol in a label field is assigned as its value the address at which the statement's code will be placed. However, the equ directive can be used to create a symbol and assign it some other value, such as a constant. A label can contain up to 32 characters. Its first character must be an alphabetic character or one of the special characters '_' or '.' . Its other characters can be alphabetic characters, digits, '_', or '.' . A label followed by '#' is declared external. The cc compiler places a '_' character at the end of all labels that it generates. 3.3 Opcodes The assembler supports the standard MOS Tech instruction mnemonics for both the 6502 and 65C02 processors. The directives it supports are defined below. 3.4 Arguments A statement's argument can specify a register, a memory location, or a constant. A memory location can be referenced using any of the standard 6502 or 65C02 addressing modes, and using the standard MOS Tech syntax. A memory location reference or a constant can be an expression containing any of the following operators: * multiply / divide + add - substract # constant = constant < low byte of expression > high byte of expression Expression are evaluated from left to right with no precedence as to oprator or parantheses. 3.5 Constants The default base for numeric constants is decimal. Other bases are specified by the following prefixes or suffixes: Base Prefix Suffix 2 % b,B 8 @ o,O,q,Q 10 null,& null 16 $ h,H A character constant consist of the character, preceded by a single quote. For example: 'A . 3.6 Directives The following paragraphs describe the directives that are supported by the assembler. END end The end directive defines the end of the source statements. CSEG cseg The cseg directive selects a module's code segment: information generated by statements that follow a cseg directive is placed in the module's code segment, until another segment-selection directive is encountered. DSEG dseg The dseg directive selects a module's data segment: information generated by statements that follow a dseg directive is placed in the module's data segment, until another segment-selection directive is encountered. EQU symbol equDIAGNOSTICSThe equ directive creates a symbol named symbol (if it doesn't already exist), and assigns it the value of the expression expr. PUBLIC public [, ...] The public directive identifies the specified symbols as having external scope. If a specified symbol was created within the module that's being assembled (by being defined in a statement's label field), this directive allows it to be accessed by other modules. If a symbol was not created within the module that's being assembled, this directive tells the assembler that the symbol was created and made public in another module. BSS bss , The bss directive creates a symbol named symname and reserves size bytes of space for it in the uninitialized data segment. The symbol cannot be accessed by other modules. GLOBAL global , The global directive creates a symbol named symname that other modules can access using the global and public directives. If other modules create symnam using just the global directives, then symnam will be located in a program's uninitialized data area. In this case, the amount of space reserved in this area for symnam will equal the largest value specified by the size fields in the global statements that define symnam. If other modules define in a public statement, but none of them create symnam (by specifying it in a label field), then symnam will still be located in the uninitialized data segment and space will be reserved for it as defined above. If one of the modules both define symnam using a public statement and creates the symbol by specifying it in a label field, then symnam will be located in the program's code or data segment and no space will be reserved for it in the uninitialized data segment. ENTRY entry The entry directive defines the symbol symnam as being a program's entry point. When a program is linked, the linker normally places a jump instruction at the program's data base address. If the linker found a module containing an entry directive, it sets the target of the jump to the location that was specified in the last entry directive that it found; otherwise, it sets the target to the beginning of the program's code segment. FCB [label] fcb <value>[,<value>...] Each value in an fcb directive causes one or more bytes of memory to be allocated and then initialized to the specified value. The memory is allocated in the currently active segment (code, or data, as defined by the last segement-selection directive). FCC [label] fcc "string" The fcc directive allocates a filed that has the same number of characters as are in string, and places string in it. The field is placed in the currently-active segment. RMB [label] rmb <expr> The rmb directive reserves a lield containing expr bytes in the currently-active segment. The contents of the field is not defined. INSTXT instxt <file> instxt "file" instxt /file/ The instxt directive causes the assembler to suspend assembly of the current source file and to assemble the source that's in file. When done, the assembler will continue assembling the original file. The assembler can serach for a file in several directories. If file is surrounded by quotes or by slashes, the assembler will begin the search at the current directory; it will search the directories specified in the -I option and the INCLUDE environment variable. If file is surrounded by <>, the assembler will search just the -I and INCLUDE directories.
If the assembler fails they return -1 as there value that, for example, tells shell-scripts to stop immediatly.SEE ALSO
bye /* Apple // utility */DESCRIPTION
bye tranfers control of the processor to the Apple monitor program that's in ROM, by jumping to location $FF65. To return to the SHELL from the monitor, enter the command 3D0G On machines having the autostart ROM, you can also reenter the SHELL by hitting the reset key.<< Back to Top
cat [file] [file] ... /* Apple // and UNIX utility */DESCRIPTION
cat reads each file in sequence and writes it to its standard output device. If no files are specified, cat reads from its standard input device. Each argument can specify a complete or partial file name, in the normal manner. By default, cat's standard input and output devices are assigned to the console. Either or both can also be redirected to another device or file, if desired, in the normal fashion. cat is a built-in SHELL command.EXAMPLE
cat hello.c Writes hello.c to the screen. cat hello.c input.c > cat.out Writes hello.c and input.c to cat.out. cat Copies typed characters to the screen. cat > ../newfile Copies typed characters to ../newfile. cat < /stdio/printf.c > tmp.c Equivalent to cat /stdio/printf.c > tmp.cSEE ALSO
cc [-options] filename.c /* Apple // ProDOS utility */ cci [-options] filename.c The 6502 compiler is named cc on native versions of Aztec C65 and c65 on cross development versions. Relocatable object files are named .r on the MS-DOS cross development version of Aztec C65.DESCRIPTION
cc translates C source code into native 6502 assembly language source code. cci translates C source code into assembly language source for a "pseudo machine"; in an executable program, cci-compiled code must be interpreted by a special Aztec C routine. The compilers were implemented according to the language description in the Kernighan and Ritchie book "The C Programming Language". This description of the compilers is divided into three subsections: which describe how to use the compilers, compiler options and error processing. To the operator and programmer, the two compilers are very similar. In the discussion that follows, we will use the name cc when describing features that are common to both compilers. Where differences exist, we will say so. 1. COMPILER OPERATING INSTRUCTIONS cc is invoked by a command of the form: cc [-options] filename.c where [-options] specify optional parameters, and filename.c is the name of the file containing the C source program. Options can appear either or after the name of the C source file. The compiler reads C source statements from the input file, translates them to assembly language source, and writes the result to another file. When the compiler is done, it by default activates the as assembler (cci by defaults starts the asi assembler). The assemblers translates the assembly language source to relocatable object code, writes the result to another file, and deletes the assembly language source file. The -A option tells the compiler not to start the assembler. 1.1 The C source file The extension on the source file name is optional. If not specified, it's assumed to be .c . For example, with the following command, the compiler will assume the file name is text.c : cc text The compiler will append .c to the source file name only if it does find a period in the file name. So if the name of the source file really doesn't have an extension, you must compile it like this: cc filename. The period in the name prevents the compiler from appending .c to the name. 1.2 The ouput files 1.2.1 Creating an object code file Normally, when you compile a C program you are interested in the relocatable object code for the program, and not in its assembly language source. Because of this, the compiler by defaults writes the assembly language source for a C program to an intermediate file and then automatically starts the assembler. The assembler then translates the assembly language source to relocatable object code, writes this code to a file, and erases the intermediate file. By default, the object code generated by a cc-started assembly is sent to a file whose name is derived from that of the file containing the C source by changing its extension to .o (the default extension for a cci-started assembly is .i). This file is placed in the directory that contains the source file. For example, if the compiler is started with the command cc prog.c the file prog.o will be created, containing the relocatable object code for the program. The name of the file containing the object code created by a compiler-started assembler can also be explicitly specified when the compiler is started, using the compiler's -O option. For example, the command cc -O myobj.rel prog.c compiles and assembles the C source that's in the file prog.c, writing the object code to the file myobj.rel . When the compiler is going to automatically start the assembler, it by default writes the assembly language source to a temporary file named ctmpxxx.xxx, where the x's are replaced by digits in such a way that the name becomes unique. This temporary file is placed in the directory specified by the environment variable CCTEMP. If this variable doesn't exist, the file is placed in the directory specified by the current default prefix. When CCTEMP exist, the fully-qualified name of the temporary file is generated by simply prefixing its value to the ctmpxxx.xxx name. For example if CCTEMP has the value /RAM/TEMP/ then the temporary file is placed in the TEMP directory on the RAM volume. If you are interested in the assembly language source, but still want the compiler to start the assembler, specify the option -T when you start the compiler. This will cause the compiler to send the assembly language source to a file whose name is derived from that of the file containing the C source by changing its extension to .asm . The C source statements will be included as commanets in the assembly language source. For example, the command cc -T prog.c compiles and assembles prog.c, creating the file prog.asm and prog.o . 1.2.2 Creating just an assembly language file There are some programs for which you don't want the compiler to automatically start the assembler. For example, you may want to modify the assembly language generated by the compiler for a particular program. In such cases, you can use the compiler's -A option to prevent the compiler from starting the assembler. When you compile a program using the -A option, you can tell the compiler name and location of the file to which it should write the assembly language source, using the -O option. If you don't use the -O option but the -A option, the compiler will send the assembly language source to a file whose name is derived from that of the C source file changing the extension to .asm and place this file in the same directory as the one that contains the C source file. For example, the command cc -A prog.c compiles, without assembling, the C source that's in prog.c, sending the assembly language source to prog.asm . As another example, the command cc -A -O temp.a65 prog.c compiles, without assembling, the C source that's in prog.c, sending the assembly language source to the file temp.a65 . When the -A option is used, the -T option causes the compiler to include the C source statements as comments in the assembly language source. 1.3 Searching for #include files You can make the compiler search for #include files in a sequence of directories, thus allowing source files and #include files to be contained in different directories. Directories can be specified with the -I compiler option, and with the INCLUDE environment variable. The compiler itself also selects a few areas to search. The maximum number of searched areas is eight. If the file name in the #include statement specifies a directory, just that directory is searched. 1.3.1 The -I option A -I option defines a single directory to be searched. The area descriptor follow the -I, with no intervening blanks. For example, the following -I option tells the compiler to search the include directory on the ram volume: -I/ram/include 1.3.2 The INCLUDE environment variable The INCLUDE environment variable also defines a directory to be searched for #include files. For example, the following command sets INCLUDE so that the compiler will search for include files in the directory /ram/include: set INCLUDE=/ram/include 1.3.3 The search order for include files Directories are searched in the following order: 1. If the #include statement delimited the file name with the double quota character (") the current directory on the default drive is searched. If delimited by angle brackets (< >) this area isn't automatically searched. 2. The directories defined in -I options are searched, in the order listed on the command. 3. The directory defined in the INCLUDE environment variable is searched. 2. COMPILER OPTIONS There are two types of options in Aztec C compilers: machine independent and machine dependent. The machine-independent options are provided on all Aztec C compilers. They are identified by a leading minus sign. The Aztec C compiler for each target has its own, machine-dependent, options. Such are identified by a leading plus sign. The following paragraphs first summarize the compiler options and then describe them in detail. 2.1 Summary of options 2.1.1 MACHINE-INDEPENDENT OPTIONS -A Don't start the assembler when compilation is done. -Dsymbol[=value] Define a symbol to the preprocessor. -I dir Search a directory named dir for #include files. -O file Send output to file. -S Don't print warning messages. -T Include C source statements in the assembly language code output as comments. Each source statement appears before the assembly code it generates. -B Don't pause after every fifth error to ask if the compiler should continue. See the Errors subsection for details. -Enum Use an expression table having num entries. -Lnum Use an local table having num entries. -Ynum Use a case table having num entries. -Znum Use a literal table having num bytes. 2.1.2 Special Options for the ProDOS compilers +C Generate 65C02 code (cc only). +B Don't generate the statement "public .begin". +L Turn automatic variables into statics (cc only). 2.2 Detailed description of the options 2.2.1 Machine-independent options 2.2.1.1 The -D option (Define a macro) The -D option defines a symbol in the same way as the preprocessor directive, #define. It's usage is as follows: cc -Dmacro[=text] prog.c For example, cc -DMAXLEN=1000 prog.c is equivalent to inserting the following line at the beginning of the program: #define MAXLEN 1000 Since the -D option causes a symbol to be defined for the preprocessor, this can be used in conjunction with the preprocessor directive, #ifdef, to selectively include code in a compilation. A common example is code such as following: #ifdef DEBUG printf ("value: %d\n", i); #endif This debugging code would be included in the compiled source by following command: cc -DDEBUG prog.c When no substitution text is specified, the symbol is defined to have the numerical value 1. 2.2.1.2 The -I Option (Include another source file) The -I option causes the compiler to search in a specified directory for files included in the source code. The name of the directory immediately follows the -I, with no intervening spaces. For more details, see the Compiler Operating Instructions, above. 2.2.1.3 The -S Option (Be silent) The compiler considers some errors to be genuine errors and others to be possible errors. For the first type of error, the compiler always generates an error message. For the second, it generates a warning message. The -S option causes the compiler to not print warning messages. 2.2.1.4 The Local Symbol Table and the -L Option When the compiler begins processing a compound statement, such as the body function or the body of a for loop, it makes entries about the statement's local symbols in the local symbol table, and removes the entries when it finishes processing the statement. If the table overflows, the compiler will display a message and stops. Be default, the local symbol table contains 40 entries. Each entry is 26 bytes long, thus by default the table contains 640 bytes. You can explicitly define the number of entries in the local symbol table using the -L option. The number of entries immediately follows the -L, with no intervening spaces. For example, the following compilation will use a table of 75 entries, or almost 2000 bytes: cc -L75 prog.c 2.2.1.5 The Expression Table and the -E Option The compiler uses the expression table to process an expression. When the compiler completes its processing of an expression, it frees all space in this table, thus making the entire table available for the processing of the next expression. If the expression table overflows, the compiler will generate error number 36, "no more expression space", and halt. By default, the expression table contains 80 entries. Each entry is 14 bytes long, thus by default the table contains 1120 bytes. You can explicitly define the number of entries in the expression table using the -E option. The number of entries immediately follows the -E, with no intervening spaces. For example, the following compilation will use a table of 20 entries: cc -E20 prog.c 2.2.1.6 The Case Table and the -Y Option The compiler uses the case table to process a switch statement, making entries in the table for the statement's cases. When it completes its processing of a switch statement, it frees up the entries for that switch. If this table overflows, the compiler will display error 76 and halt. For example, the following will use a maximum of four entries in the case table: switch (a) { case 0: a += 1; /* one */ break; case 1: switch (x) /* two */ { case 'a': func1 (a); /* three */ break; case 'b': func2 (b); /* four */ break; } /* release the last two */ a = 5; case 3: func2 (a); /* total ends at three */ break; } /* release all entries */ By default, the table contains 100 entries. Each entry is four bytes long, thus by default, the table occupies 400 bytes. You can explicitly define the number of entries in the case table using the compiler's -Y option. The number of entries immediately follows the -Y, with no intervening spaces. For example, the following compilation uses a case table having 50 entries: cc -Y50 file 2.2.1.7 The String Table and the -Z Option When the compiler encounters a "literal" (that is, a character string), it places the string in the literal table. If this table overflow, the compiler will display error 2, "string space exhausted", and halt. By default, the literal table contains 2000 bytes. You can explicitly define the number of bytes in this table using the compiler's -Z option. The number of bytes immediately follows the -Z, with no intervening spaces. For example, the following command will reserve 3000 bytes for the string table: cc -Z3000 prog.c 2.2.1.8 The Macro/Global Symbol Table The compiler stores information about a program's macro and global symbols in the Macro/Global Symbol Table. This table is located in memory above all the other tables used by the compiler. Its size is set after all the other tables have been set. and hence can't be set by you. If this table overflows, the compiler will display the message "Out of Memory!" and halt. You must recompile, using smaller sizes for the other tables or split your C source code. 2.2.2 PRODOS OPTIONS 2.2.2.1 The +C Option (Generate 65C02 code - cc only) The +C option causes cc to generate source for a 65C02 processor. If this option isn't used, cc will generate code for a 6502 processor. 2.2.2.2 The +B Option (Don't generate reference to .begin) Normally when compiling a module, the compilers generate a reference to the entry point named .begin . Then when the module is linked into a program, the reference causes the linker to include in the program the library module that contains .begin . The +B option prevents the compilers from generating this reference. For example, if you want to provide your own entry point for a program, and its name isn't begin, you should compile the program's modules with the +B option. If you don't, then the program will be bigger than necessary, since it will contain your entry point module and the standard entry point module. In addition, the linker by default sets at the program's base adress a jump instruction to the program's entry points in several module, it will set the jump to the last encountered. 2.2.2.3 The +L Option (Turn Autos into Statics - cc only) The +L option causes the compiler to change the class of variables whose class is automatic to static. This can cause a significant increase in execution speed, since it is faster to adress static variables, which are directly addressable, than automatic variables, which are on the stack and must be indirectly addressed. Automatic variables that are declared using the auto keyword, (for example auto int i), aren't affected by the +L option: they will remain automatic. Also, if a register is available for an automatic variable that is declared using the register keyword (for example, register int i), the variable will be placed in a register and will not be turned into a static. If a register is not available, however, such a variable will be turned into a static variable. Like any other static data, an auto-turned-static is initialized to zero before the program begins. A function that recursively calls itself may not work correcty when it is compiled with the +L option. For example, the following program will print 1 when compiled without the +L option, and 100 when compiled with the +L option. main () { printf ("%d", qtest ()); } qtest () { int i; if (++i < 100) qtest (i); return (i); } 3. ERROR CHECKING Compiler errors come in two varieties - fatal and not fatal. Fatal errors cause the compiler to make a final statement and stop. Running out of memory and finding no input are examples of fatal errors. The non-fatal sort are introduced below. The compiler will report any error it finds in the source file. It will first print out a line of code, followed by a line containing the up-arrow (caret) character. The up-arrow in this line indicates where the compiler was in the source line when it detected the error. The compiler will then display a line containing the following: * The name of the source file containing the line; * The number of the line within the file; * An error code; * The symbol with causes the error, when appropriate. The compiler writes error messages to its standard output. Thus, error messages normally go to the console, but they can be associated with another device or a file by redirecting standard output in the usual manner. For example, cc prog.c errors sent to the console; cc prog.c > outerr errors sent to the file outerr. The compiler normally pauses after every fifth error, and sends a message to its standard output asking you want to continue. The compiler will continue only if you enter a line beginning with the character 'y'. If you don't want the compiler to pause in this manner, (if, for example, the compiler's standard output has been redirected to a file) specify the -B option when you start the compiler. The compiler is not always able to give a precise description of an error. Usally, it must proceed to the next item in the file to ascertain that an error was encountered. Once an error is found, it is not obvious how to interpret the subsequent code, since the compiler cannot second-guess the programmer's intentions. This may cause it to flag perfectly good syntax as an error. If errors arise at compile time, it is a general rule of thumb that the first error should be corrected first. This may clear up some of the errors which follow. If the compiler detects more error with the same symbol, it maybe is only one error (for example, a variable is not declared). The best way to attack an error is first to look up the meaning of the error code.DIAGNOSTICS
If the compilation fails the compilers return -1 as there value that, for example, tells shell-scripts to stop immediatly.SEE ALSO
cd [directory] /* Apple // and UNIX utility */DESCRIPTION
cd makes cirectory the current directory. If directory isn't specified, the current directory is set to the directory that's defined in the HOME environment variable, if this variable exist. If the specified directory doesn't exist, the current directory is unchanged. The directory argument defines the path of directories which must be passed trough to reach the new directory. The path can define a complete path from the root directory or it can define a partial path, which is assumed to begin at the current directory. cd is a built-in SHELL command.EXAMPLE
cd /work/io The directory /work/io is made the current directory. cd subs/io The directory io, which is reached from the current directory by passing through the subdirectory subs of the current directory and then into io, is made the current directory. For example, if /work was the current directory, then after this command /work/subs/io is the new current directory. cd .. The current directory is set to the parent directory of the directory which was the current before the issuance of this command. cd ../include The current directory is set to the directory which is reached by passing through the parent directory of the directory which was current before the issuance of this command and then its include subdirectory. cd ../.. The current directory is set to the directory which is reached by passing through the parent directory of the directory which was current before the issuance of this command and then to its parent directory.<< Back to Top
cmp [-l] file1 file2 /* Apple // and UNIX utility */DESCRIPTION
cmp compares two files an a character-by-character basis. When it finds a difference, it displays a message, giving the offset from the beginning of the file. If the -l option isn't specified, the program will stop after the first difference, displaying a message in the format: Files differ: character 10 If the -l option is specified, cmp will list all differences, in the format: decimal-offset hex-offset file1-value file2-valueEXAMPLE
cmp otst ntst Files differ: character 10 cmp -l otst ntst 10 a: 00 45 100 64: 1A 23<< Back to Top
cnm [-sol] file [file ...] /* Apple // utility */DESCRIPTION
cnm displays the size and symbols of its object file arguments. The files can be object modules created by the as or asi assemblers, libraries of object modules created by the lb librarian, and 'rsm' files created by the ln linker during the linking of an overlay root. For example, the following displays the size and symbols for the object module sub1.o, the library c.lib, and the 'rsm' file root.rsm: cnm sub1.o c.lib root.rsm By default, the information is sent to the console. It can be redirected to a file or device in the normal way. For example, the following commands send information about sub1.o to the display and to the file dispfile: cnm sub1.o cnm sub1.o > dispfile The first line listed by cnm for an object module has the following format: file (module): code:cc data:dd udata:uu total:tt(0xhh) where * file is the name of the file containing the module. * module is the name of the module; if the module is unamed, this field and its surrounding parentheses aren't printed. * cc is the number of bytes in the module's code segment, in decimal. * dd is the number of bytes in the module's initialized data segment in decimal. * uu is the number of bytes in the module's uninitialized data segment, in decimal. * tt is the total number of bytes in the module's three segments, in decimal. * hh is the total number of bytes in the module's three segments, in hexadecimal. If cnm displays information about more than one module, it displays four totals just before it finishes, listing the sum of the sizes of the modules' code segments, initialized data segments, and uninitialized data segments, and the sum of the sizes of all segments of all modules. Each sum is in decimal, the total of all segments is also given in hexadecimal. The -s option tells cnm to display just the sizes of the object modules. If the option isn't specified, cnm also displays information about each named symbol in the object modules. When cnm displays information about the module's named symbols, the -l option tells cnm to display each symbol's information on a seperate line and to display all of the characters in a symbol's name. If this option isn't used, cnm displays the information about several symbols on a line and only displays the first eight characters of a symbol's name. The -o option tells cnm to prefix each line generated for an object module with the name of the file containing the module and the module name in parentheses (if the module is named). If this option isn't specified, this information is listed just once for each module: prefixed to the first line generated for the module. The -o option is useful when using cnm in combination with grep. For example, the following commands will display all information about the module perror in the library c.lib: cnm -o c.lib > tmp grep perror tmp cnm displays information about an module's named symbols, that is, about the symbols that begin with something other than a dollar sign followed by a digit. For example, the symbol quad is named, so information about it would be displayed, the symbol .0123 is unnamed, so information about it would not be displayed. For each named symbol in a module, cnm displays its name, a two- character code specifying its type, and an associated value. The value displayed depends on the type of the symbol. If the first character of a symbol's type code is lower case, the symbol can only be accessed by the module, that is, it's local to the module. If this character is upper case, the symbol is global to the module: either the module has defined the symbol and is allowing other modules to access it ar the module needs to access the symbol, which must be defined as a global or public symbol in another module. The type codes are: ab The symbol was defined using the assembler's EQUATE directive, The value listed is the equated value of its symbol. The compile doesn't generate symbols of this type. pg The symbol is in the code segment. The value is the offset of the symbol within the code segment. The compiler generates this type symbol for function names. Static functions are local to the function, and so have type pg, all other functions are global, that is, callable from other programs, and hence have type Pg. dt The symbol is in the initialized data segment. The value is the offset of the symbol from the start of the data segment. The compiler generates symbols of this type for initialized variables which are declared outside any function. Static variables are local to the program and so have type dt, all other variables are global, that is, accessable from other programs, and hence have type Dt. ov When an overlay is being linked and that overlay itself calls another overlay, this tpe of symbols can appear in the 'rsm' file for the overlay that is being linked. It indicates that the symbol is defined in the program that is going to call the overlay that is being linked. The value is the offset of the symbol from the beginning of the physical segment that contains it. un The symbol is used but not defined within the program. The value has no meaning. In assembly language terms, a type of Un (the U is capitalized) indicates that the symbol is the operand of a public directive and that it is perhaps referenced in the operand field of some statements, but that the program didn't create the symbol in a statement's label field. The compiler generates Un symbols for functions that are called but not defined within the program, for variables that are declared to be extern and that are actually used within the program, and for uninitialized, global dimensionless arrays. Variables which are declared to be extern but which are not used within the program aren't mentioned in the assembly language source file generated by the compiler and hence don't appear in the object file. bs The symbol is in the uninitialized data segment. The value is the space reserved for the symbol. The compiler generates bs symbols for static, uninitialized variables which are declared outside all functions and which aren't dimensionless arrays. The assembler generates bs symbols for symbols defined using the bss assembler directive. Gl The symbol is in the uninitialized data segment. The value is the space reserved for the symbol. The compiler generates Gl symbols for non-static, uninitialized variables which are declared outside all functions and which aren't dimensionless arrays. The assembler generates Gl symbols for variables declared using the global directive which have a non- zero size.<< Back to Top
cp [-f] infile outfile /* Apple // and UNIX utility */ cp [-f] file1 [file2 ...] dirDESCRIPTION
cp copies files, and their attributes. The first form of the command, as shown above, copies infile to outfile. The second copies file1, file2, ... into the directory named dir. The -f option causes cp to automatically overwrite any existing files. If this option isn't specified and if a file to be created already exists, cp will ask if you want it overwritten. On an Apple // cp is a built-in SHELL command.EXAMPLE
The following command copies the file hello.c that is in the current directory to the file newfile.c in the /source directory: cp hello.c /source/newfile.c The next command copies all ".c" files in the /arc directory to the current (ie, the ".") directory: cp /arc/*.c .SEE ALSO
cp doesn't copy read-protected files. It only creates them.<< Back to Top
crc file1 file2 ... /* Apple // and UNIX utility */DESCRIPTION
crc computes a number, called the CRC, for the specified files. The CRC for a file is entirely dependent on the file's contents, and it is very unlikely that two files whose contents are different will have the same CRCs. Thus, crc can be used to determine whether a file has the expected contents.EXAMPLE
As an example of the usage of crc, the following command computes the crc of all files whose extension is .c: crc *.c<< Back to Top
date /* Apple // utility */DESCRIPTION
Displays the date and time. date is a built-in SHELL command.<< Back to Top
debug /* Apple // utility */DESCRIPTION
To debug a SHELL-activated program using the monitor program That's in ROM, first enter the debug command, and then enter the command to start the program. The SHELL will load the program, perform i/o redirection and pass arguments to it if necessary, then, when it sees that the debug command was entered, it will jump to the monitor. When you're done debugging return to the SHELL by entering the command: 3D0G The debug command affects only the next program that the SHELL starts. That is, for each program that you want to debug, you must first enter the debug command and then enter the command to start the program. debug is a built-in SHELL command.<< Back to Top
df [/vol] /* Apple // utility */DESCRIPTION
Displays information about disk space utilization. The optional parameter /vol defines the disk of interest. It can be the name of a file or directory. In this case, information is displayed about the disk that contains the specified file or directory. /vol can also be the single character '/' (ie, specify the SHELL's simulated root directory of the entire file system). In this case, information is displayed about all on-line disks. If /vol isn't specified, and if the current directory isn't the simulated root directory of the file system, information is displayed about the disk that contains the current directory. If /vol isn't specified, and if the current directory is the simulated root directory of the file system, information is displayed about all on-line disks.EXAMPLE
The following command displays information about the disk that contains the current directory: df The next command displays information about the /ram disk: df /ram The next command displays information about all on-line disks: df /<< Back to Top
diff [-b] file1 file2 /* Apple // and UNIX utility */DESCRIPTION
diff is a program, similar to the UNIX program of the same name, hat determines the difference between two files containing text. file1 and file2 are the names of the files to be compared. 1. THE -B OPTION The -b option causes diff to ignore trailing blanks (spaces and tabs) and to consider strings of blanks to be identical. If this option isn't specified, diff considers two lines to be the same only if they match exactly. diff will never consider blanks to match a null string, regardless of whether -b was used or not. 2. THE CONVERSION LIST diff writes, to its standard output, a "conversion list" that describes the changes that need to be made to file1 to convert it into file2. The list is organized into a sequence of items, each of which describes one operation that must be performed on file1. 2.1 Conversion Items There are three types of operations that can be specified in a conversion list item: * adding lines to file1 from file2; * deleting lines from file1; * replacing (changing) file1 lines with file2 lines. A conversion list item consists a letter describing the operation to be performed: 'a' for adding lines, 'd' for deleting line, and 'c' for changing lines. Preceding and following the letter are the numbers of the lines in file1 and file2, respectively, that are affected by the command. If a range of lines in a file are affected, just the beginning and ending line numbers are listed, seperated by a comma. So one line of the output of diff will look like file1line [,file1to] [letter] file2line [,file2to] [><] diffline 2.1.2 The affected lines As mentioned above, the lines affected by a conversion item's operation are listed after the item's command line. The affected lines from file1 are listed first, flagged with a preceding '<'. The come the affected lines from file2, flagged with a preceding '>'. The file1 and file2 lines are seperated by the line ---. Since no lines from file1 are affected by an 'add' conversion item, only the file2 lines that will be added to file1 are listed, and the seperator line '---' is omitted. 3. DIFFERENCES BETWEEN THE UNIX AND MANX VERSION OF DIFF The Manx und UNIX versions of diff are actually most similar when the latter program is invoked with the -h option. As with the UNIX diff when used with the -h option, the Manx diff works best when changed stretches are short and well sperated, and works with files of unlimited length. Unlike the UNIX diff, the Manx diff doesn't support the options e, f, or h and requires that both operands to diff be actual files. Because of this, the Manx version of diff doesn't support the features of the UNIX version which allows one operand to be a directory name, (to specify a file in that directory having the same name as the other operand), and which allows one operand to be '-' (to specify diff's standard input instead of a file).<< Back to Top
echo [arg1] [arg2] ... /* Apple // utility */DESCRIPTION
echo writes its arguments, seperated by blanks and terminated by a newline, to its standard output device. The ouput thus goes, by default, to the screen. It can also be redirected to another device or file in the normal manner. echo is a built-in SHELL command.<< Back to Top
grep [-cflnv] pattern [files] /* Apple // and UNIX utility */DESCRIPTION
grep is a program, similar to the UNIX program of the same name, that searches files for lines containing a pattern. By default, such lines are written to grep's standard output. 1. INPUT FILES The files parameter is a list of files to be searched. If no files are specified, grep searches its standard input. Each file name can specify a single file to be searched. 2. OPTIONS The following options are supported: v print all lines that don't match the pattern c print just the name of each file and the number of matching lines that it contained l print the names of just the files that contain matching lines n precede each matching line that's printed by its relative line number within the file that contains it f a character in the pattern will match both its upper and lower case equivalent 3. PATTERNS A pattern consists of a limited form of regular expression. It describes a set of character strings, any of whose members are said to be matched by the regular expression. Some patterns match just a single character, others, which match strings, can be constructed from those that match single characters. In the following paragraphs, we'll first describe the patterns that match a single character, and then describe patterns that match strings of characters. 3.1 Matching single characters The patterns that match a single character are these: * an ordinary character (that is, one other than the special characters described below) matches itself * a period (.) is a pattern that matches any character except newline. * a non-empty string of characters enclosed in square brackets, [], matches aby one character in that string If the string begins with the caret character,(^), the regular expression matches any character except the other enclosed characters and newline. The '^' has this special meaning only if its the first character of the string. The minus character, (-), can be used to indicate a range of consecutive ASCII characters ( [0-9] is equivalent to [0123456789] ). * A backslash, (\), followed by a special character matches the special character itself. The special characters are: ., *, [, and \, which are always special, except when they appear in square backets, ([]). caret, (^), which is special when it is at the beginning of an entire regular expression (as discussed in 3.4) and when it immediately follows the left of a pair of square brackets. $, which is special at the end of an entire regular expression (discussed in 3.4). 3.2 Matching character string Patterns can be concatenated. In this case, the resulting pattern matches strings whose substrings match each of the concatenated patterns. 3.3 Matching repeating characters A pattern can be built by appending an asterick, (*), to a pattern that match a single character. The resulting pattern matches zero or more occurences of the single-character pattern. 3.4 Matching strings that begin or end lines An entire pattern may be constrained to match only character strings that occur at the beginning or the end of a line, by beginning or ending the pattern with the character '^' or '$', respectively.EXAMPLE
4.1 Simple string matching The following command will search the files file1.txt and file2.txt and print the lines containing the word heretofore: grep heretofore file1.txt file2.txt If you aren't interested in the specific lines of these files, but just want to know the names of the file containing the word heretofore, you could enter grep -l heretofore file1.txt file2.txt The above two examples ignore lines in which heretofore contains capital letters, such as when it begins a sentence. The following command will cover this situation: grep -lf heretofore file1.txt file2.txt grep processes all option at once, so multiple options must be specified in one dash parameter. For example, the command grep -l -f heretofore file1.txt file2.txt won't work. 4.2 The special character '.' Suppose you want to find all lines in the file prog.c that contain a four-character string whose first and last characters are 'm' and 'n', respectively, and whose other characters you don't care about. The command grep m..n prog.c will do the trick, since the special character '.' matches any single character. 4.3 The backslash character There are occasions when you want to find the character '.' in a file, and don't want grep to consider it to be special. In this case, you can use the backslash character, (\), to turn off the special meaning of the next character. For example, suppose you want to find all lines containing .PP. Entering grep .PP prog.doc isn't adequate, because it will find lines such as THE APPLICATION OF since the '.' matches the letter 'A'. But if you enter grep /.PP prog.doc grep will print just what you want. The backslash character can be used to turn off the special meaning of any special character. For example, grep \\n prog.c finds all lines in prog.c containing the string '\n'. 4.4 The dollar sign and caret ($ and ^) Suppose you want to find the number of the line on which the definition of the function add occure in the file arith.c. Entering grep -n add arith.c isn't good, because it will print lines in which add is called in addition to the line you're interested in. Assuming that you begin all function definitions at the beginning of a line, you could enter grep ^add arith.c to accomplish purpose. The character '$' is a companion to '^', and stands for 'the end of the line'. So if you want to file all lines in file.doc that end in the string time, you could enter grep time$ file.doc And the following will finds all lines that contain just .PP: grep ^\.PP$ 4.5 Using brackets Suppose that you want to find all lines in the file file.doc that begins with a digit. The command grep ^[0123456789] file.doc will do just that. This command can be abbreviated as grep ^[0-9] file.doc And if you wanted to print all lines that don't begin with a digit, you could enter grep ^[^0-9] file.doc or grep -v ^[0-9] file.doc 4.6 Repeated characters Suppose you want to find all lines in the file prog.c that contain strings whose first character is 'e' and whose last character is 'z'. The command grep e.*z prog.c will do that. The 'e' matches an 'e', the '.*' matches zero or more arbitrary characters, and the 'z' matches a 'z'. 5. DIFFERENCES BETWEEN THE MANX AND UNIX VERSION OF GREP The Manx and UNIX version of grep differ in the options they accept and the patterns they match. 5.1 Option differences The option -f is supported only by the Manx grep. The option -b and -s are supported only by the UNIX grep. 5.2 Pattern differences Basically, the patterns accepted by the Manx grep are a subset of those accepted by the UNIX grep. The Manx grep doesn't allow a regular expression to be surrounded by '\(' and '\)'. The Manx grep doesn't accept the construct '\{m\}'. The Manx grep doesn't allow a right bracket, ']', to be specified within brackets. Quoted strings can't be passed to the Manx grep. For example, the Manx grep won't accept grep 'this is a fine kettle of dish' file.doc<< Back to Top
hd [-r] [+n[.]] file1 ... /* Apple // utility */DESCRIPTION
hd displays the contents of one or more files in hex and ascii to its standard output. file1, file2, ... are the names of the files to be displayed. +n specifies the offset into the file where the display is to start, and defaults to the beginning of the file. if +n is followed by a period, n is assumed to be a decimal number, otherwise, it's assumed to be hexdecimal. Each file will be displayed beginning at the last specified offset.EXAMPLE
hd +16b oldtest newtest +0 junk Displays the data forks of the files oldtest and newtest, beginning at offset 0x16b, and of the file names junk beginning at its first byte. hd -r +1000. tstfil Displays the contents of the resource fork of tstfil, beginning at byte 1000.<< Back to Top
lb library [options] [mod1 mod2 ...] /* Apple // utility */ Relocatable object files are named .r on the MS-DOS cross development version of Aztec C65.DESCRIPTION
lb is a program that creates and manipulates libraries of object modules. The modules must have been created by the Manx assembler. 1 THE ARGUMENTS TO LB 1.1 The library arguments When started, lb acts upon a single library file. The first argument to lb (library, in the synopsis) is the name of this file. The filename extension for library is optional, if not specified, it's assumed to be .lib. 1.2 The option argument There are two types of option argument: function code options, and qualifier options. These options will be summarized in the following paragraphs, and then described in detail below. 1.2.1 Function code options When lb is started, it performs one function on the specified library, as defined by the options argument. The functions that lb can perform, and their corresponding option code, are: Function Code create a library (no code) add modules to a library -a, -i, -b list library modules -t move library within a library -m replace modules -r delete modules -d extract modules -x ensure modules uniqueness -u help -h In the synopsis, the options argument is surrounded by square brackets. This indicates that the argument is optional, if a code isn't specified, lb assumed that a library is to be created. 1.2.2 Qualifier options In addition to a functions code, the options argument can optionally specify a qualifier, that modifies lb's behavior as it is performing the requested function. The qualifiers and their codes are: verbose -v silent -s The qualifier can be included in the same argument as the function code, or as a seperate argument. 1.3 The mode arguments The arguments mod1, mod2, etc are the names of the object modules, or the files contianing these modules, that lb is to use. For some functions, lb requires an object module name, and for others it requires the name of a file containing and object module. In the latter case, the file's extension is optional, if not specified, lb assumes that it's .o. 1.4 Reading arguments from another file lb has a special argument, -f filename, that causes it to read command line arguments from the specified file. When done, it continues reading arguments from the command line. Arguments can be read from more than one file, but the file specified in a -f filename argument can't itself contain a -f filename argument. 2. BASIC FEATURES OF LB In this section we want to describe tha basic features of lb. With this knowledge in hand, you can start using lb, and then read about the rest of the features of lb at your leisure. The basic things you need to know about lb, and which thus are described in this section, are: * How to create a library * How to list the name of modules in a library * How modules get their names * Order of modules in a library * Getting lb arguments from a file 2.1 Creating a library A library is created by starting lb with a command line that specifies the name of the library file to be created and the names of the files whose object modules are to be copied into the library. It doesn't contain a function code, and it's this absence of a function code that tells lb that it is to create a library. An object module file from which modules are read into a new library can itself be a library created by lb. In this case, all the modules in the library are copied into the new library. 2.1.1 The temporary library When lb creates a library or modifies an existing library, it first creates a new library with a temporary name. If the function was successful performed, lb erases the file having the same name as the specified library, and then renames the new library, giving it the name of the specified library. Thus, lb makes sure it can create a library before erasing an existing one. Note that there must be room on the disk for both the old library and the new. 2.2 Getting the table of contents for a library To list the names of the modules in a library, use lb's -t option. The list will include some **DIR** entries. These identify blocks within the library tthat contain control information. They are created and deleted automatically as needed, and cannot be changed by you. 2.3 How modules get their names When a module is copied into a library from a file containing a single object module (that is, from object module generated by the Manx assembler), the name of the module within the library is derived from the name of the input file by deleting the input file's volume, path and extension components. An input file can itself be a library. In this case, a module's name in the new library is the same as its name in the input library. 2.4 Order in a library The order of modules in a library is important, since the linker makes only a single pass through a library when it is searching for modules. When lb creates a library, it places modules in the library in the order in which it reads them. The ord utility program can be used to create a library whose modules are optionally sorted. 2.5 Getting lb arguments from a file For libraries containing many modules, it is frequently inconvenient, if not impossible, to enter all the arguments to lb on a single command line. In this case, lb's -f filename feature can be of use: when lb finds this option, it opens the specified file and starts reading command arguments from it. After finshing the file, it continues to scan the command line. Arguments in a -f file can be seperated by any sequence of whitespace characters ('whitespace' being blanks, tabs, and newlines). Thus, arguments in a -f file can be on seperate lines, if desired. The lb command line can contain multiple -f arguments, allowing lb arguments to be read from several files. A -f file can contain any valid lb argument, except another -f. That is, -f files can't be nested. 3. ADVANCED LB FEATURES 3.1 Adding modules to a library lb allows you to add modules to an existing library. The modules can be added before or after a specified module in the library or can be added to the beginning or end of the library. The options that select lb's add function are: Option Function -b target add modules before the module target -i target same as -b target -a target add modules after the module target -b+ add modules to the beginning of the library -i +same as -b+ -a +add modules to the end of the library In any lb command that selects the add function, the name of the files containing modules to be added follows the add option code (and the target module name, when appropriate). A file can contain a single module or a library of modules. Modules are addes in the order that they are specified. If a library is to be added, its modules are added in the order they occur in the input library. 3.2 Moving modules within a library Modules which already exist in a library can be easily moved about, using the move option, -m. As with the option for adding modules to an existing library, there are several forms of move functions: Option Meaning -mb target move modules before the module target -ma target move modules after the module target -mb+ move modules to the beginning of the library -ma+ move modules to the end of the library In the lb command, the names of the modules to be moved follows the 'move' option code. The modules are moved in the order in which they are found in the original library, not in the order in which they are listed in the lb command. 3.3 Deleting modules Modules can be deleted from a library using lb's -d option. The command for deletion has the form lb libname -d mod1 mod2 ... where mod1, mod2, ... are names of the modules to be deleted. 3.4 Replacing modules The lb option 'replace' is used to replace one module in a library with one or more other modules. The 'replace' option has the form lb libname -r target where target is the name of the module being replaced. In a command that uses the 'replace' option, the names of the files whose modules are to replace the target module follow the 'replace' option and its associated target module. Thus, an lb command to replace a module has the form: lb library -r target mod1 mod2 ... 3.5 Uniqueness lb allows libraries to be created containing duplicate modules, where one module is a duplicate of another if it has the same name. The option -u causes lb to delete duplicate modules in a library, resulting in a library in which each module name is unique. In particular, the -u option causes lb to scan through a library, looking at module names. Any modules found that are duplicates of previous modules are deleted. 3.6 Extracting modules from a library The lb option -x extracts modules from a library and puts them in sperated files, without modifying the library. The names of the modules to be extracted follows the -x option. If no modules are specified, all modules in the library are extracted. When a module is extracted, it's wriiten to a new file, the file has the same name as the module and extension .o. 3.7 The 'verbose' option The 'verbose' option, -v, causes lb to be verbose, that is, to tell you what it's doing. This option can be specified as part of another option, or all by itself. 3.8 The 'silence' option The 'silence' option, -s, causes lb to not display its signon message. This option is especially useful when redirecting the output of a list command to a disk file, as described below. 3.9 Rebuilding a library The following commands provide a convenient way to rebuild a library: lb exmpl -st > tfil lb exmpl -f tfil The first command writes the names of the modules in exmpl.lib to the file tfil. The second command then rebuilds the library, using as arguments the listing generated by the first command. The -s option to the first command prevents lb from sending information to tfil that would foul up the second command. The names send to tfil entries for the directory blocks, **DIR**, but these are ignored by lb. 3.10 Help The -h option is provided for brief lapses of memory, and will generate a summary of lb functions and options (same as calling lb without any argument). It is producing an output like: append/insert: -[+/-] target move module: -m[+/-] target replace module: -r target delete module: -d target uniqueness: -u extract module: -x [target] table listing: -t specify obj extension: -e usage: lb libraryname -[key][position] [posname] [modules] ...<< Back to Top
ln [-options] file.o [file.o ...] [lib.lib ...] The 6502 linker is named ln on native versions of Aztec C65 and ln65 on cross development versions. Relocatable object files are named .r on the MS-DOS cross development version of Aztec C65.DESCRIPTION
The ln linker has two functions: * It ties together the pieces of a program which have been compiled and assembled separately; * It converts the linked pieces to a format which can be loaded and executed. The pieces must have been created by the Manx assembler. The first section of this chapter presents a brief introduction to linking and what the linker does. If you have previous experience with linkage editors, you may wish to continue reading with the second section, entitled "Using the Linker". There you will find a concise description of the command format for the linker. 1. INTRODUCTION TO LINKING 1.1 Relocatable Object Files The object code produced by the assembler is "relocatable" because it can be loaded anywhere in memory. One task of the linker is to assign specific addresses to the parts of the program. This tells the operating system where to load the program when it is run. 1.2 Linking hello.o It is very unusual for a C program to consist of a single, self-contained module. Let's consider a simple program which prints "hello, world" using the function, printf. The terminology here is precise; printf is a function and not an intrinsic feature of the language. It is a function which you might have written, but it already happens to be provided in the file c.lib . This file is a library of all the standard i.o functions. It also contains many support routines which are called in the code generated by the compiler. These routines aid in integer arithmetic, operating system support, etc. When the linker sees that a call to printf was made, it pulls the function from the library and combines it with the "hello, world" program. The link command would look like this: ln hello.o c.lib When hello.c was compiled, calls were made to some invisible support functions in the library. So linking without the standard library will cause some unfamiliar symbols to be undefined. All programs will need to be linked with one of the versions of c.lib . Initially, you can use c.lib itself. Later on, if you find that c.lib doesn't suit your requirements, you can use one of the other versions. 1.3 The Linking Process Since the standard library contains only a limited number of general purpose functions, all but the most trivial programs are certain to call user-defined functions. It is up to the linker to connect a function call with the definition of the function somewhere in the code. In the example given below, the linker will find two function calls in file 1. The reference to func1 is "resolved" when the definition of func1 is found in the same file. The following command ln file1.o c.lib will cause an error indicating that func2 is an undefined symbol. The reason is that the definition of func2 is in another file, namely file2.o . The linkage has to include this file in order to be successful: ln file1.o file2.o c.lib file1 file2 func1 () func2 () { { printf ("hello, "); printf ("world"); return; return; } } main () { func1 (); func2 (); } 1.4 Libraries A library is a collection of object files put together by a librarian. Libraries intended for use with ln must be built with the Manx librarian, lb. All the object files specified to the linker will be "pulled into" the linkage; they are automatically included in the final executable file. However, when a library is encountered, it is searched. Only those modules in the library which satisfy a previous function call are pulled in. 1.5 For example Consider the "hello, world" example. Having looked at the module, hello.o, the linker has built a list of undefined symbols. This list includes all the global symbols that have been referenced but not defined. Global variables and all function names are considered to be global symbols. The list of undefined's for hello.o includes the symbol printf. When the linker reaches the standard library, this is one of the symbols it will be looking for. It will discover that printf is defined in a library module whose name also happens to be printf. (There is not any necessary relation between the name of a library module and the functions defined within it.) The linker pulls in the printf module in order to resolve the reference to the printf function. Files are examined in the order in which they are specified on the command line. So the following linkages are equivalent: ln hello.o ln c.lib hello.o Since no symbols are undefined when the linker searches c.lib in the second line, no modules are pulled in. It is good practice to leave all libraries at the end of the command line, with the standard library last of all. 1.6 The Order of Library Modules For the same reason, the order of the modules within a library is significant. The linker searches a library once, from beginning to end. If a module is pulled in at any point, and that module introduces a new undefined symbol, then that symbol is added to the running list of undefined's. The linker will not search the library twice to resolve any references which remain unresolved. A common error lies in the following situation: module of program references (function calls) main.o getinput, do_calc input.o gets calc.o put_value output.o printf Suppose we build a library to hold the last three modules of this program. Then our link step will look like this: ln main.o proglib.lib c.lib But it is important that proglib.lib is built in the right order. Let's assume that main() calls to functions, getinput () and do_calc(). getinput() is defined in the module input.o. It in turn calls the standard library function gets(). do_calc() is in calc.o and calls put_value(). put_value() is in output.o and calls printf(). What happens at link time if proglib.lib is built as follows? proglib.lib input.o output.o calc.o After main.o, the linker has getinput and do_calc undefined (as well as some other support functions in c.lib). Then it begins the search of proglib.lib. It looks at the library module, input, first. Since that module defines getinput, that symbol is taken off the list of undefined's. But gets is added to it. The symbols do_calc and gets are undefined when the linker examines the module, output. Since neither of these symbols are defined there, that module is ignored. In the next module, calc, the reference to do_calc is resolved but put_value is a new undefined symbol. The linker still has gets and put_value undefined. It then moves on to c.lib, where gets is resolved. But the call to put_value is never satisfied. The error from the linker will look like this: Undefined symbol: put_value_ This means that the module defining put_value was not pulled into the linkage. The reason, as we saw, was that put_value was not an undefined symbol when the output module was passed over. This problem would not occur with the library built this way: proglib.lib input.o calc.o output.o The standard libraries were put together with much care so that this kind of problem would not arise. Occasionally it becomes difficult or impossible to build a library so that all references are resolved. In the example, the problem could be solved with the following command: ln main.o proglib.lib proglib.lib c.lib The second time through proglib.lib, the linker will pull in the module output. The reason this is not the most satisfactory solution is that the linker has to search the library twice; this will lengthen the time needed to link. 2. USING THE LINKER The general form of a linkage is as follows: ln [-options] file.o [file.o ...] [lib.lib ...] The linker can create programs having the following types: * PRG programs, which can only be executed in the SHELL environment; * BIN programs, which can be executed in either in the SHELL or the Basic Interpreter environments; * SYS programs, which are ProDOS system programs. By default, the linker creates a PRG program. The +B option makes it create a BIN program, and the +S option make it create a SYS program. When creating a BIN or SYS program, you will also have to include the startup routine samain.o in the program. 2.1 The executable file The name of the executable output file can be selected using the -O linker option. If this option isn't used, the linker will derive the name of the output file from that of the first object file listed on the command line, by deleting its extension. In the default case, the executable file will be located in the directory in which the first object file is located. For example, ln prog.o c.lib will produce the file prog. The standard library, c.lib, will have to be included in most linkages. A different output file can be specified with the -O option, as in the following command: ln -O program mod1.o mod2.o c.lib This command also shows how several individual modules can be linked together. A "module", in this sense, is a section of a program containing a limited number of functions, usally related. These modules are compiled and assembled separately and linked together to produce an executable file. 2.2 Libraries Several libraries of object modules are provided with the Aztec C65. The most freqently-used of these are c.lib, which contains 6502 versions of the non-floating point functions, and m.lib, which contains 6502 versions of the floating point functions. Other libraries are provided with some versions of Aztec C65. All programs must be linked with one of the versions of c.lib. In addition to containing 6502 versions of all the non-floating point functions it contains internal functions which are called by compiler-generated code, such as functions to perform long arithmetic. Programs that perform floating point operations must be linked with one of the version of m.lib, in addition to a version of c.lib. The floating point library must be specified on the linker command line before c.lib . Libraries of user modules can also be searched by the linker. These are created with the Manx lb program, and must be listed on the linker command line before the Manx libraries. For example, the following links the module program.o, searching the libraries mylib.lib, new.lib, m.lib and c.lib for needed modules: ln program.o mylib.lib new.lib m.lib c.lib Each of the libraries will be searched once in the order in which they appear on the command line. Libraries can be conveniently specified using the -L option. For example, the following command is equivalent to the one above: ln -O program.o -lmylib -lnew -lm -lc For more information, see the description of the -L option below. 3. LINKER OPTIONS 3.1 Summary of options 3.1.1 General Purpose Options -O file Write executable code to the file named file. -Lname Search the library name.lib for needed modules. -F file Read common arguments from file. -T Generate a symbol table file. -M Don't issue warning messages. -N Don't abort if there are undefined symbols. -V Be verbose. 3.1.2 Options for Segment Address Specification -B addr Set the program's base address to the hex value addr. -C addr Set the starting address of the program's code segment to the hex value addr. -D addr Set the starting address of the program's data segment to the hex value addr. -U addr Set the starting offset of the program's uninitialized data segment to the hex value addr. 3.1.3 Option for Overlay Usage -R Create a symbol table to be used when linking overlays. +C size Reserve size bytes at end of the program's code segment (the overlay's code segment is loaded here). size is a hex value. +D size Reserve size bytes at end of the program's code and uninitialized data segements (the overlay's data is loaded here). size is a hex value. 3.1.4 Special Options for ProDOS +B Create a BIN program. +S Create a SYS program. +H start,end Define a hole in the program, whose beginning and ending addresses are hex values start and end. 3.2 Detailed description of the options 3.2.1 General Purpose Options: 3.2.1.1 The -O option The -O option can be used to specify the name of the file to which the linker is to write the executable program. The name of this file is in the parameter that follows the -O. For example, the following command writes the executable program to the file progout: ln -O progout prog.o c.lib If this option isn't used, the linker derives the name of the executable file from that of the first input file, by deleting its extension. 3.2.1.2 The -L option The -L option provides a convenient means of specifying to the linker a library that is should search, when the extension of the library is .lib. The name of the library is derived by concatenating the value of the environment varibale CLIB, the letters that immediately follow the -L option, and the string .lib. For example, with the libraries subs.lib, io.lib, m.lib and c.lib in a directory specified by CLIB, you can link the module prog.o, and have the linker search the libraries for needed modules by entering ln prog.o -lsubs -lio -lm -lc CLIB is set using the SHELL's set command. For example, the following command defines CLIB when the libraries are in the directory /ln/lib: set CLIB=/ln/libs/ Note the terminating slash on the CLIB variable: this is required since the linker simply prepends the value of the CLIB variable to the -L string. 3.2.1.4 The -F option -F file causes the linker to merge the contents of the given file with the command line arguments. For example, the following command causes the linker to create an executable program in the file myprog. The linker includes the modules myprog.o, mod1.o and mod2.o in the program, and searches the libraries mylib.lib and c.lib for needed modules. ln myprog.o -F argfile c.lib where the file argfile, contains the following: mod1.o mod2.o mylib.lib The linker arguments in argfile can be seperated by tabs, spaces, or newlines. There are several uses for the -F option. The most obvious is to supply the names of modules that are frequently linked together. Since all the modules named are automatically pulled into the linkage, the linker does not spend any time in searching, as with a library. Furhermore, any linker option except -F can be given in a -F file. -F can appear on the command line more than once, and in any order. The arguments are processed in the order in which they are read, as always. 3.2.1.5 The -T option The -T option creates a disk file which contains a symbol table for the linkage. This file is just a text file which lists each symbol with a hexadecimal address. This address is either the entry point for a function or the location in memory of a data item. A perusal of this file will indicate which functions were actually included in the program. The symbol table file will have the same name as that of the file containing the executable program, with extension changed to .sym . 3.2.1.6 The -M option The linker issues the message "multiply defined symbol" when it finds a symbol that is defined with the assembly language directives global or public in more than one module. The -M option causes the linker to supress this message unless the symbol is defined in more than one public directive. To maintain compability with the previous versions of Aztec C, the linker will generate code for a variable that is defined in multiple global statements and in at most one public statement, and also issue the "multiply defined symbol" message. Thus, if you use the global and public directives in this way, and don't want to get this message, use the -M option to supress them. The definition of a symbol in more that one public directives is never valid, so the -M option doesn't supress messages in this case. 3.2.1.7 The -N option Normally, the linker halts without generating an executable program if there are undefined symbols. The -N option causes the linker to go ahead and generate an executable program anyway. 3.2.1.8 The -V option The -V option causes the linker to send a progress report of the linkage to the screen as each input file is processed. This is useful in tracking down undefined symbols and errors which may occur while linking. 3.2.2 Option for segment address specification The linker organizes a program into three segments: code, initialized data, and uninitialized data areas. You can define the starting address of these segments using the -C, -D, and -U linker options, respectively. A fourth option, -B, will set the "base address" of the program. These options are followed by the desired offset, in hex. By default, the base address of a PRG or BIN program is 0x800, while the base address of a SYS program is 0x2000. Also by default, a program's code segment starts three bytes after the base address, its initialized data segment follows the code, and its uninitialized data follows the initialized data. A file created by the linker contains a memory image of the program, from its base address through the end of its code or initialized data segments (whichever is higher). This image is loaded into memory, with the first byte in the file loaded at the program's base address. By default, a program is expected to begin execution at its base address. Most programs have a startup routine, which performs initialization activities and then calls the program's main function. This entry point to the startup routine is usually somewhere in the middle of the program, so at the base address the linker will normally set a jump instruction to the entry point. You can explicitly specify that a label in a module is an entry point by placing the label in the operand field of the module's assembly language entry directive. For example, the crt0 module in c.lib contains the function .begin . This label is dclared in a public directive and also in the module's entry directive. When a C module is compiled, the compiler always generates a reference to .begin; thus, when the program is linked, ln will include the crt0() module from c.lib and place a jump to .begin at the program's base address. If the linker doesn't find a startup routine when it links a program, it won't set the jump instruction at the program's base address. In this case, if you don't specify a starting offset for the program's code segment, it will right at the base address. For example, the following command sets the base address of prog to 0x4000: ln -B 4000 -O prog prog.o -lc Because none of the other segment selection options were used in this example, the program's code will begin at offset 0x4003, followed by its initialized data, followed by its uninitialized data. In the next example, the program's base address is set to 0x900 the offset of its code, initialized data, and uninitialized data segments to 0x2000, 0x2800, and 0x3000, respectively. ln -B 900 -C 2000 -D 2800 -U 3000 prog.o -lc 3.2.3 Options for Overlay Usage The -R option causes the linker to generate a file containing the symbol table. It's used when linking a program which calls overlays. The name of the symbol table file is derived from that of the executable file by changing the extension to .rsm . The file is placed in the same directory as the executable file. The linker reserves space in a program between its uninitialized data area and its heap, into which the program's overlay will be loaded. The amount of space equals the sum of the values that you define using the +C and +D options. For example, ln +C 3000 +D 1000 prog.o -lc will reserve 0x400 bytes for overlays. 3.2.4 Special Option for ProDOS 3.2.4.1 The +B Option The +B option causes the linker to set the type of a file containing a created program to BIN. 3.2.4.2 The +S Option The +S option causes the linker to set the type of a file containing a created program to SYS and to set the default base address for the program to 0x2000. 3.2.4.3 The +H option The +H option defines a "hole", that is an area of memory into which the linker should not place a program's code or data. You can create at most four holes in a program using +H options. The option has the following form: +H start,end where start and end are the addresses, in hex, of the hole's starting and ending addresses. For example, suppose you want to create a program, line, that uses the primary graphics page (between addresses 0x2000-0x4000) and that begins at address 0x800. The following command will link the program: ln +H 2000,4000 line.o -lc The linker will place as much of the program's code and data as possible in the area between 0x800-0x2000, and place any additional code and data in the area above 0x4000. The linker creates a program's code segment by concatenating module code segments, until and unless a module's code overlaps a reserved area. If this occurs, the linker moves the module's entire code segment above the reserved area, in the first non-reserved area in which it will entirely fit, and then continues the concatenation of module code segments. The linker creates a program's initialized data segement in the same way: it concatenates module initialized data segments as much as possible, without overlapping a reserved area and without breaking a module's initialized data segment into discontigous pieces. Because the linker won't break up a module's code segment or data segment, it's likely that some space below a hole will be left unused by the linker.DIAGNOSTICS
If the linker fails it return -1 as its value that, for example, tells shell-scripts to stop immediatly.SEE ALSO
lock file1 file2 ... /* Apple // utility */ unlock file1 file2 ...DESCRIPTION
These commands lock and unlock the specified files. When locked, a file can't be removed, renamed, or written to. lock and unlock are built-in SHELL commands.<< Back to Top
ls [-option] [name1 name2 ...] /* Apple // and UNIX utility */DESCRIPTION
ls displays information about the files and directories name1, name2, ... If no names are specified, ls displays information about all the files and directories in the current directory. A name can optionally specify multiple files, using the "wildcard characters" * and ?. These have their standard meaning: * matches one or more characters, and ? matches a single character. ls sends the information to its standard output. This information thus by default is sent to the console, but can be redirected to a file or other device in the normal way. ls by default displays information in 'short form', listing just the names of the specified files and directories. You can also specify the -l option to cause ls to display information in 'long form', listing lots of information. When ls sends information in short form to the console, the names are in columns on the screen, with a dash preceding directory names. When the information is sent to a file or other device, the names are listed one per line, and a directory name isn't by default preceded by a dash. ls usally sorts the list it's going to display. By default, the list is sorted alphabetically, you can also specify options to cause ls to sort based on other the list such 'last modified' time and file size, and, for a given criteria, to sort in the reverse of the normal order. ls supports the following options: -l list in long form. -p When listing in short form, and redirected, precede directory names with a dash. -t sort by 'last-modified' time. -s sort by file size. -r reverse the order of the sort. -x don't sort the file list. LONG FORMAT The -l option causes the listing to be made in 'long format', in which additional information is displayed for each file. In this case, the listing for a file or directory has the following format: flags type (aux_type) size date name where: * name is the name of the file or directory. * date is the date and time at which it was last modified. * size is the number of bytes that have been written to it. * aux_type is its aux_type field (for a program, this is its load adress). * type defines the contents of the file or directory. * flags defines other attributes of the file or directory. FLAGS FIELD The flags field consists of five characters, each defines whether or not the file has a certain attribute. If the file or directory has all these attributes, the falgs field will be "debwr". If the file or directory doesn't have a particular attribute, the attribute's characters is replaced in the list by a dash, '-'. The meanings of the characters are: d deletable. e erasable. b needs to be backed up. w writable. r readable. TYPE FIELD The type field defines the type of the file. Possible values are: PRG File conatins a program that can only be run in the SHELL environment. BIN File contains a type program that can be run in the SHELL or Basic environment. SYS File contains a ProDOS system file. DIR Directory. TXT This is the only other type of file created by the Aztec programs. fopen, open, and related functions also create files or type TXT. MOUNTED VOLUMES The SHELL pretends that the file system has a root directory, and that all volume directories are subdirectories of this root directory. So to diplay the names of all mounted volumes, enter the command ls / And to display the names of all mounted volumes along with the numbers of the slot and drives that contain them, enter the command ls -l /<< Back to Top
mkdir dirname1 dirname2 ... /* Apple // and UNIX utility */DESCRIPTION
mkdir creates one or more directories, named dirname1, dirname2, ... An empty directory can be removed with the rm command on an Apple // and with rmdir command under UNIX.SEE ALSO
mv [-f] infile outfile /* Apple // and UNIX utility */ mv [-f] file1 [file2 ...] dirDESCRIPTION
mv moves files, and their attributes. The original files then cease to exist. The first form of the command, as shown above, copies infile to outfile. The second copies file1, file2, ... into the directory named dir. The -f option causes mv to automatically overwrite any existing files. If this option isn't specified and if a file to be created already exists, mv will ask if you want it overwritten. In both forms, mv will simply change the name of the original file to that of the target file if the two files are in the same directory. It physically copies a file and then deletes the original only when the directories of the two files differ. mv is a built-in SHELL command on an Apple //.EXAMPLE
The following command moves the file hello.c that is in the current directory to the file newfile.c in the /source directory: mv hello.c /source/newfile.c The next command moves all ".lib" files in the /ln directory to the /pl/lib directory: mv /ln/*.lib /pl/lib<< Back to Top
obd objfile /* Apple // utility */DESCRIPTION
obd lists the loader items in an object file. It has a single parameter, which is the name of the object file.<< Back to Top
ord [-v] [infile [outfile]] /* Apple // utility */DESCRIPTION
ord sorts a list of object file names. A library of the object modules that is generated from the sorted list by object module librarian, lb, will have a minimum number of 'backward references', that is, global symbols that are defined in one module and referenced in a later module. Since the specification of a library to the linker causes it to search the library just once, a library having no backward references need be specified just once when linking a program, and a library having backward references may need to be specified multiple times. infile is the name of a file containing an unordered list of file names. These files contain the object modules that are to be put into a library. If infile isn't specified, this list is read from ord's standard input. The file names can be seperated be space, tab, or newline characters. outfile is the name of the file to which the sorted list is written. If it's not specified, the list is written to ord's standard output. outfile can only specified if infile is also specified. The -v option causes ord to be verbose, sending messages to its standard error device as it proceeds.SEE ALSO
pr s1 [s2 ...] /* Apple // utility */DESCRIPTION
pr initializes the devices that are in slots s1, s2, ..., by calling each device's ROM. pr is a built-in SHELL command.EXAMPLE
The following command initializes the card in slot 2 by calling address 0xC200: pr 2<< Back to Top
pwd /* Apple // and UNIX utility */DESCRIPTION
pwd prints the name of the current directory. The name is written to pwd's standard output device. Hence, the name is printed on the screen, by default, and can be redirected to another device or file, if desired. pwd is a built-in SHELL command.SEE ALSO
rm file [file ...] /* Apple // and UNIX utility */DESCRIPTION
rm removes the specified files or directories. rm will not remove locked files or non-empty directories. Under UNIX rm doesn't remove directories. Locking is handled different.EXAMPLE
The following command removes the files file1.bak and file2.bak from the current directory: rm file1.bak file2.bak<< Back to Top
set /* Apple // utility */ set VAR=string set VAR= set [-+x] [-+e] [-+n]DESCRIPTION
set is used to examine and set environment variables, to set exec file options, and to enable the trapping of errors by the SHELL. set is a built-in SHELL command. Displaying and setting of environment variables: The first form listed for set causes set to display the name and value of each environment variable. The second form assigns string to the environment variable VAR. The third form removes the variable VAR from the SHELL environment. Setting Exec file options: x Command line logging. With this option enabled, before a command line in an exec file is executed, it's logged to the screen. By default, this option is disabled. e Exit prematurely. With this option enabled, a command which terminates with a non-zero return code causes the exec file to be aborted. By default, this option is enabled. n Non-execution. With this option enaabled, commands in the exec file aren't executed. By default, this option is disabled. Preceding an option's character with a minus sign enables the option, and preceding it with a plus sign disables it.<< Back to Top
shift [n] /* Apple // utility */DESCRIPTION
shift causes the values assigned to an exec file variable to be reassigned to the next lower-numbered exec file variable. n is the number of the lowest-numbered variable whose value is to be reassigned, and defaults to 1. Thus, shift causes the exec file variable $1 to be assigned with the value of $2, $2 to be assigned with $3, and so on. The original value assigned to $1 is lost. When all arguments to the exec file have been shifted out, $1 is assigned to the null-string. shift is a built-in SHELL command.EXAMPLE
The following exec file, del, is passed a directory as its first argument and the names of files within the directory that are to be removed: set j=$1 shift loop i in $* rm $j/$i eloop In this example, j is an environment variable. The first two statements in the exec file save the name of the directory and then shift the directory name out of the exec file variables. The loop then repeatedly calls rm to remove one of the specified files from the directory. Entering del . file1.bak file2.bak will remove the files file1.bak and file2.bak from the current directory.<< Back to Top
sqz file [outfile] /* Apple // utility */DESCRIPTION
sqz compresses an object module that was created by the Manx assembler. The first parameter is the name of the file containing the module to be compressed. The second parameter, which is optional, is the name of the file to which the compressed module will be written. If the output file is specified, the original file isn't modified or erased. If the output file isn't specified, sqz creates the compressed module in a file having a temporary name, erases the original file, and renames the output file to have the name of the original file. The temporary name is different from the input file name by having the extent .sqz. If the output file isn't specified and an error occurs during the creation of the compressed module, the original file isn't erased or modified.<< Back to Top
tty -sy -bxx /* Apple // utility */DESCRIPTION
tty is a terminal emulaion program that allows an Apple // operator to talk to another computer. To the other system, the Apple // will appear to be a terminal that supports some of the special features of the ADM-3A terminal. tty reads characters from the keyboard and writes them to a serial interface. It also reads characters characters from this interface and writes them to the console. This interface must be compatible with the Super Serial Card. The -s option defines the number of the slot containing the interface. The number immediately follows the -s, with no intervening spaces. If this option isn't specified, the interface is assumed to be in slot 2. The -b option defines the baud rate of the serial interface. The baud rate immediately follows the -b option, with no intervening spaces. If this option isn't specified, the baud rate is assumed to be 9600. To exit tty, type control-2 (ie, type the '2' key while holding down the control key).<< Back to Top
ved [-tn] [-gprog] file [+1,c msg] /* Apple // utility */DESCRIPTION
ved is a screen oriented text editor that has some of the features of the UNIX vi editor. If ved is invoked with a file name, that file will be loaded into the memory buffer, otherwise it will be empty. ved will only edit text files: binary files cannot be edited. ved does all its editing in memory and is thus limited in the size of files that it will edit. In ved, the memory buffer is never completely empty. There will always be at least one newline in the buffer. THE SCREEN ved has a 1000 character limit on the size of a line. If a line is longer than the width of the screen, it will wrap to the next line. If a line starts at the bottom of the screen, and its too wide to fit, the line will not be displayed. Instead, the '@' character will be displayed. Likewise, at the end of the file, all lines beyond the end will consist only of a single '-' on each line. A number of commands take a numeric prefix. This prefix is echoed on the status line as it is typed. MOVING AROUND IN THE FILE The normal mode of ved is command mode. During command mode, there are a number of ways to move the cursor around the screen and around the whole file. newline - move to beginning of the next line. - - move to the start of the previous line. space - move to the next character of the line. backspace - move to the previous character. 0 - move to the first character of this line. $ - move to the last character of this line. h - move to the top line of the screen. l - move to the bottom line of the screen. b - move to the first line of the file. g - move to the n'th line of the file. /string - move to hte next occurence of 'string'. DELETING TEXT When the cursor is in the appropriate spot, there are two commands used to delete existing text. x - delete characters on the current line, beginning at the cursor and continuing up to, but not including the newline. dd - delete lines starting with the current line. The x and dd commands can be prefixed with a number, which defines the number of characters or lines to be deleted. If a number isn't specified, just one character or line is deleted. Note that deleting the last character of the line (newline character) causes the following line to be appended to the current line. INSERTING TEXT To add new text, hitting 'i' key will cause the top line of the screen to indicated that you are now in<< Back to Topmode. To exit insert mode, type ESCAPE. To insert a control character which means something special to ved into a text file, first type control-v followed be the control character itself. Control characters are displayed as '^X', where X is the appropiate character. Typing 'o' will cause a new line to be created below the current line, and the cursor will be placed on that line and the editor placed into mode. MOVING TEXT AROUND There are three commands used for moving text around. These commands make use of a 1000 character yank buffer. The contents of this buffer is retained across files. yy - yank lines starting with the current line into the yank buffer. yd - yank lines starting with the current line and then delete them. p - "put" the lines in the yank buffer after the current line. The yank buffer is not modified. A number can be prefixed to the yank commands, defining the number of lines to be yanked. If a number isn't specified, just one line is yanked. MISCELLANEOUS COMMANDS The 'z' command redraws the screen with the current line in the center of the screen. The 'r' command repalaces the character under the cursor with the next character typed. FILE-RELATED COMMANDS When in command mode, if the ':' key is hit, a ':' will be displayed on the status line. At this point, a number of special file-related commands may be given. :f - displays info about the current file. :w file - writes the buffer to the specified file name. :w - writes the buffer to the last specfied file. :e[!] file - clears the buffer and prepares file for editing. :r file - reads the named file into the buffer. :q[!] - exits the editor. In the above table, square brackets surrounding a character indicate that the character is optional. The exclamation mark tells ved to execute the commands in which it's specified, even if the file that's currently being edited has been modified since it was last written to disk. APPLE RELATED INFORMATION In order to use VED on older Apple //'s, which don't have a full ASCII keyboard, you need to have the single wire switch key modification installed. You can then enter upper and lower case alphabetic characters using the SHIFT key. You can enter special character used by C programs by typing a control character, that is, by holding down the control key and then typing another key. The following table lists these control characters and the characters to which they are translated. In this table, ^X is an abbreviation for "type X while holding the control key down". The first column identifies control codes that you type, the second identifies the characters to which control codes are translated when the keyboard is in lower case mode (that is, when the SHIFT key is off). The last column identifies the characters to which control codes are translated when the keyboard is in upper case mode. Press: To get (lower): To get (upper): ^P ` @ ^A { [ ^E | \ ^R } ] ^N ~ ^ ^C DEL _ ^Q ESC ^U TAB ^U is generated by typing the 'right arrow key'. To exit insert mode, type is ESC key. In addition to the ESC key, you can type control-Q to exit VED's mode. This is usefull on some older Apple //e's, for which ESC is intercepted by the ROM and never gets back to VED. Out of insert mode, the cursor can be moved around using the space bar to move rigth and the left arrow to move left.