---------------------------------------------------------------- | | | | | | | | | ================================================ | | | | | | | | | | | ***** Digital Research C ***** | | | | | | | | for the CP/M-86 Family | | | | of Operating Systems | | | | | | | | --------------- | | | | | | | | READ.ME File Notes | | | | | | | | - June 1983 - | | | | | | | | Digital Research Inc. | | | | P.O. Box 579 | | | | Pacific Grove, CA 93950 | | | | | | | ================================================ | | | | | | | | This file presents enhancements and modifications | | made to Digital Research C Language software and | | documentation. Changes described in this file | | apply to Digital Research C compiler software | | Version 1.0 and the "C Language Programmer's Guide | | for the CP/M-86 Family of Operating Systems" | | First Edition: April 1983. | | | | You can print the information in this file on your | | line printer using 8 by 11 inch paper with the | | printer set to 6 lines per inch. You can trim the | | pages along the dotted lines and place the pages | | in your product documentation binder. | | | | | | | | | | | | | | | | | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes June 1983 | | | | | | | | Table of Contents | | ================================================ | | | | SOFTWARE NOTES . . . . . . . . . . . . . . . . 1 | | | | | | DOCUMENTATION UPDATES . . . . . . . . . . . . 2 | | | | Creating a C Work Disk . . . . . . . . . . 2 | | Option Switch -a . . . . . . . . . . . . . 3 | | Function Directory . . . . . . . . . . . . 5 | | execl Function . . . . . . . . . . . . . . 7 | | setjmp and longjmp Functions . . . . . . . 8 | | toascii, tolower, toupper Functions . . . 9 | | Start-up Routines . . . . . . . . . . . .10 | | Miscellaneous Notes . . . . . . . . . . .13 | | | | ================================================ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | i. | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Software Notes | | | | | | | | Software Notes | | ================================================ | | | | * Version 1.0 of the C compiler requires 112K of | | random access memory for execution in addition to | | the operating system. Different implementations | | of the operating system vary in size. | | | | * Version 1.02 of the LINK86 linkage editor which is | | supplied as part of the Digital Research C package | | is required for use with the C compiler. Do not | | use LINK86 versions 1.0, 1.01, or 1.0A supplied | | with earlier versions of Digital Research software | | products. | | | | * Digital Research C does not run under the IBM | | proprietary version of CP/M-86 due to operating | | system updates they do not provide. DRI offers an | | expanded, low-priced version of CP/M-86 for the | | IBM Personal Computer. | | | | * The sample start-up routine, STARTUP.A86, contains | | logic to set up the CP/M-86 operating environment | | for program execution under any of the four memory | | models: small, medium, compact, and big. Set the | | appropriate conditional assembly switch at the | | beginning of STARTUP.A86 before assembling to | | select the desired model. | | | | * The execl function only works under the small and | | and medium memory models. | | | | | | | | | | | | | | | | | | | | | | | | | | Page 1 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Documentation | | | | | | | | DOCUMENTATION UPDATES | | =============================================== | | | | All documentation updates indicated in this file | | apply to the "C Language Programmer's Guide for the | | CP/M-86 Family of Operating Systems" First Edition | | April 1983. Text modifications appear between the | | symbols: >> and <<. | | | | | | Creating a C Work Disk | | ========================================= | | | | Substitute the following text for the third | | paragraph and everything that follows the third | | paragraph in Section 1.5, A Simple Demonstration, | | on page 1-5. Page 1-6 remains unchanged. | | | | | | >>First, make back-up copies of your master C product | | disks and store the original disks in a safe place. | | Your operating system disk should be in drive A. | | | | 1) Create a C work disk. | | | | Using a file copy program, such as PIP, create a C | | work disk that contains the three compiler files | | required for minimum configuration, the linkage | | editor, the small model system library, and | | SAMPLE.C. If you do not have enough room on disk | | for all the files, you can place the linkage editor | | and library on a separate disk. Your work disk or | | disks should contain all of the following files. | | | | o R.CMD -- program loader | | o DRC.CMD -- compiler supervisory module | | o DRC860.CMD -- preprocessor | | o DRC861.CMD -- parser and code generator | | o LINK86.CMD -- linkage editor | | o SYSLIBS.L86 -- small model system library | | o SAMPLE.C -- sample program | | | | | | Page 2 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Documentation | | | | | | | | With your operating system disk in drive A place | | your new C work disk that contains SAMPLE.C in | | drive B. SAMPLE.C uses a simple for-loop and the | | printf function to print a short series of messages. | | You can display the SAMPLE.C program on your | | terminal with the CP/M-86 type command. Make sure | | drive B is the default drive and enter the | | following command: | | | | B>TYPE SAMPLE.C << | | | | | | Option Switch -a | | ========================================= | | | | Substitute the following text for all of page 2-5. | | | | | | >>The -a option switch executes LINK-86 automatically | | at the end of compilation. You must specify object | | files and any libraries other than the system | | library after the -a in the compiler command line. | | Alternatively, you can specify a LINK-86 input file | | using the INPUT option. Refer to Section 7.11 in | | the Programmer's Utilities Guide for more | | information on the LINK-86 INPUT option. | | | | The following command line example compiles a | | program named PROGRAM.C and automatically links the | | object file that the compiler creates with the | | small model system library. Notice that you do not | | have to specify the object file name or library | | file name explicitly after the -A if that object | | file is the only file to be linked with the system | | library on the default drive. | | | | B>DRC PROGRAM -A | | | | In this example, the compiler, LINK-86, and the | | small model system library are all on the default | | | | Page 3 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Documentation | | | | | | | | drive (B:). You can use the -3 option switch to | | specify a drive other than the default drive for | | LINK-86. | | | | The compiler compiles PROGRAM.C according to the | | small memory model and names the object file | | PROGRAM.OBJ both by default. The compiler creates | | a special object record in PROGRAM.OBJ that tells | | LINK-86 which system library to search for required | | routines depending on which memory model you | | specify for compilation. Note that the appropriate | | system library file must be on the default drive. | | Otherwise, LINK-86 displays the NO FILE error | | message indicating that you must specify the | | library and drive location explicitly. The object | | record automatically specifies the LINK-86 SEARCH | | option for library files. Therefore, LINK-86 only | | links modules from the system library that are | | referenced in PROGRAM.C. Without the SEARCH option | | LINK-86 links in the entire system library, making | | the executable program unnecessarily large. The | | preceding example creates an executable program | | named PROGRAM.CMD. | | | | To link multiple object files and libraries, you | | must specify each filename explicitly after the -A | | including the name of the object file that the | | compiler creates. Use commas to separate each | | filespec after the -A in the command line. The | | following example compiles the program named | | PROGRAM.C, then links the object file that the | | compiler creates with an object file named | | PROGTWO.OBJ and the small model system library. | | Notice that you do not have to specify the .OBJ | | filetype explicitly for the object files after the | | -A. | | | | B>DRC PROGRAM -APROGRAM,PROGTWO | | | | The next example is identical to the first example, | | except the small model system library is on the D | | drive. Notice that you must specify the object | | | | Page 4 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Graphics Errors | | | | | | | | file that the compiler creates explicitly after the | | -A whenever you have additional explicit filespecs. | | | | B>DRC PROGRAM -APROGRAM,D:SYSLIBS.L86[S] | | | | Remember, in this case, you must specify the object | | file that the compiler creates, the library file | | drive location, the library filename, and the | | LINK-86 SEARCH option explicitly. | | | | The last example is exactly the same as the first | | example, except LINK-86 is on drive D. In this | | case, the system library is on the default drive. | | You do not have to specify the object file and | | library file explicitly. | | | | B>DRC PROGRAM -A -3D: | | | | Remember, compiler command lines cannot exceed 128 | | characters. << | | | | | | Function Directory | | ========================================= | | | | Substitute the following table for Table 3-3 on | | page 3-4. | | | | | | >> Table 3-3. System Library Function Directory | | --------------------------------------------------- | | Function Page Function Page | | | | abs 3-5 index 3-30 | | access 3-6 isatty 3-31 | | atan 3-57 log 3-32 | | atoi 3-7 log10 3-32 | | atof 3-7 longjmp 3-50 | | atol 3-7 lseek 3-33 | | brk 3-8 malloc 3-9 | | calloc 3-9 mktemp 3-34 | | | | Page 5 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Function Directory | | | | | | | | chmod 3-10 open 3-35 | | chown 3-10 opena 3-35 | | clearerr 3-20 openb 3-35 | | close 3-11 perror 3-36 | | cos 3-12 printf 3-38 | | creat 3-13 putc 3-41 | | creata 3-13 putchar 3-41 | | creatb 3-13 putl 3-41 | | ctype 3-14 puts 3-43 | | exit 3-16 putw 3-41 | | _exit 3-16 qsort 3-44 | | exp 3-17 rand 3-45 | | fabs 3-18 read 3-46 | | fclose 3-19 realloc 3-9 | | fdopen 3-21 rewind 3-24 | | feof 3-20 rindex 3-30 | | ferror 3-20 sbrk 3-8 | | fflush 3-19 scanf 3-47 | | fgetc 3-25 setjmp 3-50 | | fgets 3-29 sin 3-12 | | fileno 3-20 sprintf 3-38 | | fopen 3-21 sqrt 3-51 | | fprintf 3-38 sscanf 3-47 | | fputc 3-41 srand 3-45 | | fputs 3-43 strcat 3-52 | | fread 3-23 strcmp 3-53 | | free 3-9 strcpy 3-54 | | freopen 3-21 strlen 3-55 | | fscanf 3-47 strncat 3-52 | | fseek 3-24 strncmp 3-53 | | ftell 3-24 strncpy 3-54 | | fwrite 3-23 swab 3-56 | | getc 3-25 ttyname 3-58 | | getchar 3-25 tan 3-57 | | getl 3-25 tell 3-33 | | getpass 3-27 ungetc 3-59 | | gets 3-29 unlink 3-60 | | getpid 3-28 write 3-61 | | getw 3-25 | | | | | | | | Page 6 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes execl Function | | | | | | execl Function | | ========================================= | | | | Please add the following function description to | | Section 3 of the C Language Programmer's Guide. | | | | | | >>The execl function passes control from an executing | | C program to another C program. You can chain any | | number of C programs for execution. However, once | | you pass control to a new program, you cannot | | effectively return to the original program. The | | new program overlays the original program in memory. | | Therefore, if you chain back to the original | | program, all data from the first execution are lost. | | | | Specify the name of a file that contains the | | program to chain to and any arguments that the new | | program needs for execution. You must specify at | | least one argument in addition to the filename. | | The argument must point to a null-terminated string | | that is the same as the filename string. This | | calling syntax procedure is based on UNIX | | conventions. | | | | Declarations: | | | | int execl(); | | char *name, *arg1, *arg2; | | | | Calling Syntax: | | | | ret = execl(name, arg1, arg2, ..., NULLPTR); | | | | Arguments: | | | | name -- pointer to the null-terminated | | filename string | | argX -- pointers to null-terminated | | character strings | | NULLPTR -- macro defined in PORTAB.H equal | | to 0 | | | | Page 7 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes setjmp and longjmp | | | | | | | | Returns: | | | | ret -- -1 if the function fails | | | | Note: If execl returns to the original program, an | | error has occured. The function returns a -1 and | | the errno function is set to indicate the error. << | | | | | | setjmp and longjmp Functions | | ========================================= | | | | Substitute the following text for all of page 3-50. | | | | | | >>The setjmp and longjmp functions enable a program | | to execute a nonlocal GOTO. Use the setjmp | | function to save the program environment at | | specific point in the flow of execution and to | | specify a return location for the longjmp call. | | You can then call longjmp from any point after the | | setjmp call. | | | | The longjmp function simulates a return from a call | | to setjmp. First, longjmp returns a value to | | setjmp as specified in the second argument in the | | longjmp call. Secondly, execution continues at the | | instruction immediately following the setjmp call | | in the program. | | | | If the function that invokes setjmp returns before | | longjmp is called, the saved environment is lost. | | The setjmp function saves the program environment | | in a variable of type jmp_buf. The type jmp_buf is | | defined in the include file setjmp.h. | | | | Declarations: | | | | #include | | int xret, ret, setjmp(); | | jmp_buf env; | | | | Page 8 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes to----- Functions | | | | | | | | Calling Syntax: | | . | | . | | xret = setjmp(env); | | . | | . | | longjmp(env, ret); | | | | Arguments: | | | | env -- contains the saved environment | | ret -- the desired return value from setjmp | | | | Returns: | | | | xret -- 0 when setjmp is called initially, | | then copied from ret when longjmp is | | called << | | | | | | toascii, tolower, toupper Functions | | ========================================= | | | | Please add the following function descriptions to | | Section 3 of the C Language Programmer's Guide. | | | | | | >>The toascii, tolower, and toupper functions are | | character conversion functions implemented as | | macros in the include file CTYPE.H. You must | | include CTYPE.H in any program that uses any of | | these three functions. Do not declare functions | | that are implemented as macros. Arguments that | | involve side effects might work incorrectly and | | should be avoided. | | | | The tolower function converts an upper-case letter | | to the corresponding lower-case letter. The | | toupper function converts a lower-case letter to | | the corresponding upper-case letter. The toascii | | function simply turns off all bits in a character | | | | Page 9 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Start-up Routines | | | | | | representation that are not part of a standard | | ASCII character. toascii is provided for | | compatibility with other systems. | | | | Declarations: | | | | #include | | | | int ret; | | | | Calling Syntax: | | | | ret = tolower(charac); | | ret = toupper(charac); | | ret = toascii(charac); | | | | Arguments: | | | | charac -- a single character to convert | | | | Returns: | | | | ret -- the converted character | | | | Note: tolower and toupper can accept character | | arguments represented by integers in the range 0 | | to 255. << | | | | | | Start-up Routines | | ========================================= | | | | Substitute the following text for Section 2.2. | | | | >>A start-up routine controls the execution of a | | program. It sets up the operating environment for | | program execution by initializing the stack pointer, | | segment registers, and heap. The start-up routine | | is contained in the system library and linked into | | the executable program automatically. | | | | When the C compiler encounters the function name | | | | Page 10 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Start-up Routines | | | | | | main() during compilation, the compiler generates a | | jump instruction to a routine named _START. _START | | is the standard start-up routine in the system | | library that sets up the operating environment to | | execute a program under CP/M-86. After setting up | | the environment, _START calls the program's "main" | | routine for execution. The "main" routine returns | | control to _START at the conclusion of execution. | | Lastly, _START calls the EXIT function to return | | control to the operating system. | | | | The source file named STARTUP.A86 on one of your C | | product disks is an example of a start-up routine | | written in assembly language. Study STARTUP.A86 to | | learn more about start-up routines. | | | | You can compile and link programs intended for | | stand-alone execution. Stand-alone programs do not | | use the support services of an operating system, | | but interface directly with the system hardware. | | In other words, a stand-alone rogram is a systems | | level program such as an operating system. | | | | A stand-alone program accesses certain machine | | support subroutines in the system library, such as | | the long divide and long shift routines. You | | cannot access machine support subroutines | | explicitly. The compiler generates code to access | | them implicitly. | | | | To create an executable stand-alone program, object | | modules created with the C compiler must be linked | | with the appropriate system library and a start-up | | routine that sets up the desired target operating | | environment. Remember, when the C compiler | | encounters the function name main() during | | compilation, the compiler generates a jump | | instruction to a routine named _START. The _START | | module in the system library sets up the operating | | environment for CP/M-86. You must write a new | | start-up routine for your new target environment. | | The new start-up routine that you write must also | | | | Page 11 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Rresearch C READ.ME File Notes Start-up Routines | | | | | | be named _START. However, when linking the program | | your new start-up routine module must appear first | | in the LINK86 command line. As a result, LINK-86 | | does not link in the standard _START that is | | contained in the system library. | | | | LINK-86 produces a .CMD file that is executable in | | your desired target environment. The following | | LINK-86 command line example creates a stand-alone | | program named PROG from the object modules MOD1.OBJ, | | MOD2.OBJ, and MOD3.OBJ. The file STARTUP1.OBJ | | contains the start-up routine, _START specially | | written for the target environment. LINK-86 | | searches the default drive automatically for the | | proper system library. | | | | B>LINK86 PROG=STARTUP1,MOD1,MOD2,MOD3 | | | | Note that the start-up module must appear first in | | the LINK86 command line. The system library must | | always appear after the new start-up module in the | | command line if the system library is specified | | explicitly. The object modules can appear in any | | order. | | | | You can specify a different drive location for the | | system library in the link command line. The | | following example links the three object modules | | with the compact model library. The library is on | | the d drive. | | | | B>LINK86 PROG=STARTUP1,MOD1,MOD2,MOD3,d:SYSLIBC.L86[S] | | | | The LINK-86 search option, [S], after the library | | specification selects only the routines from the | | library that the program requires. If you omit the | | search option, LINK-86 links the entire library | | into the .CMD file, making the executable program | | unnecessarily large. You can use the LINK-86 MAP | | option to make sure the proper routines are loaded | | from SYSLIB. Refer to the Programmer's Utilities | | Guide for more information on LINK86. << | | | | Page 12 | | | ---------------------------------------------------------------- ---------------------------------------------------------------- | Digital Research C READ.ME File Notes Miscellaneous | | | | | | | | Miscellaneous Notes | | ========================================= | | | | * The function described on page 3-55 is the strlen | | function, not strnlen. | | | | * Vertical bars, |, are used to separate text items | | typographically and should not be taken literally. | | For example, see Table 2-1 on page 2-3. | | | | * The -d option switch, described in Table 2-1 on | | page 2-3 and on page 2-6, defines names in lower | | case only. For example, the following command | | line defines the name aabbcc for the preprocessor. | | | | B>DRC PROGRAM -DaAbBcC | | | | * The atof function described on page 3-7 returns a | | value declared as double, not long. | | | | * The textual descriptions for the C compiler error | | messages contained in the file DRC.ERR have been | | rewritten for additional clarity and readability. | | The text in Appendix C of the C Language | | Programmer's Guide is still technically correct. | | You can modify the messages in DRC.ERR to read as | | you desire. Use your text editor in non-document | | mode. | | | | * The strncat function described on page 3-52 | | copies a maximum number of characters, n, from | | string s2 to the end of string s1. | | | | * The strncpy function described on page 3-54 | | copies exactly n characters from string s2 to s1. | | It will truncate or pad with nulls if n is not | | equal to the length of string s2. | | | | | | END OF READ.ME FILE | | | | | | Page 13 | | | ----------------------------------------------------------------