.CH "Compile Time Facilities" .# .MH "Include File Organization" The C compiler package comes with several standard header files which perform a number of functions for the C programmer. All include files are kept in the directory =incl=. .pp To maintain compatibility with the previous release of the C compiler, the file "=cdefs=" which the C compiler automatically includes (unless you use the "-f" option) is still "=incl=/swt_def.c.i". This is also in accordance with the Subsystem naming convention for other "standard" include files. However, [ul all] other C include files end in ".h" (for "header"), which is the Unix convention (this should make porting code a little easier as well). .pp The "=cdefs=" file itself has been considerably reorganized for the second release. This organization is discussed below. .# .SH "=incl=/swt_def.c.i" This file now contains very few actual definitions. Instead, it [bf #include]s separate files to provide the same functionality as it previously did. .pp We have reorganized the include files to both increase the available functionality, and to separate the features into appropriate, self-contained, "modules". So that previous programs which depend on "=cdefs=" to contain everything need from breaking, "=cdefs=" includes the files it needs. All the include files have been organized so that they may be included more than once. The definitions will only take effect the first time. .pp The following identifiers are defined in "=cdefs=" for use in determining what kind of hardware and software environment the program will run in. This is useful for writing code designed to be ported to more than one computing system. The identifiers are: .be 4 #define gtswt 1 /* using Software Tools */ #define primos 1 /* os is primos */ #define prime 1 /* hardware is prime */ #define pr1me 1 /* another name for prime */ .ee We have [bf #define]d the identifier "gtswt" instead of just plain "swt", since "swt" is the name of the routine you have to call in order to exit to the Subsystem. .pp You would use these identifiers for tailoring your code to different environments. For instance .be #ifdef gtswt /* code to do nifty stuff for Software Tools */ #else #ifdef unix /* code to do nifty stuff for Unix */ #else /* code to do nifty stuff in a generic environment */ #endif #endif .ee .pp "=cdefs=" then includes the following four files (discussed below). .be 4 #include "=incl=/stdio.h" #include "=incl=/ctype.h" #include "=incl=/swt.h" #include "=incl=/ascii.h" .ee Following the discussion of these four main files, we briefly discribe the other include files which are available. .# in alphabetical order, no less. .# .SH "=incl=/stdio.h" This file contains the declarations and definitions needed to use the C Standard I/O Library. .pp The following functions, macros, and symbolic constants are available for the programmer to use. (There are others, whose names begin with '_', which the programmer should not need to use, so they aren't discussed here). .sp .nf .ta 9 17 25 33 41 49 57 .ta 9 15 21 27 33 39 45 51 57 typedef ... FILE;[tc]The standard type FILE. .sp /* declaration of functions */ extern long ftell(); extern FILE *fopen(), *fdopen(), *freopen(), *popen(); extern char *fgets(), *gets(); extern char *strcat(), *strcpy(), *strncpy(), *strpbrk(), *strtok(); extern char *strchr(), *strrchr(), *index(), *rindex(); .sp stdin[tc][tc]Standard Input. stdout[tc][tc]Standard Output. stderr[tc][tc]Standard Error Output (Standard Output 3). stdin1[tc][tc]Subsystem name for stdin. stdout1[tc][tc]Subsystem name for stdout. stdin2[tc][tc]Standard Input Port 2. stdout2[tc][tc]Standard Output Port 2. stdin3[tc][tc]Standard Input Port 3. stdout3[tc][tc]Standard Output Port 3 (Error Output). tty[tc][tc]File pointer which is [ul always] the terminal. errin[tc][tc]Another name for stdin3. errout[tc][tc]Subsystem name for stderr. .sp EOF[tc][tc]End of file indicator (not a valid character). NULL[tc][tc]The empty pointer. BUFSIZ[tc][tc]A convenient buffer size (used a lot on Unix). TRUE[tc][tc]Represents logical true. FALSE[tc][tc]Represents logical false. .sp L_cuserid[tc]The length of a string to hold a user id. L_ctermid[tc]The length of a string to hold a terminal name. L_tmpnam[tc]The length of a string to hold a temporary file name. P_tmpdir[tc]The (string) name of a directory for temporary files. .sp getchar()[tc]Get a character from stdin. putchar(ch)[tc]Put a character on stdout. .sp feof(fp)[tc]Did EOF happen on this file? ferror(fp)[tc]Did an error occur on this file? clearerr(fp)[tc]Clear all error flags for this file. fileno(fp)[tc]Give the SWT file descriptor for the FILE pointer. .fi .ta .pp Any functions which don't return [bf int], and which are not declared in "=incl=/stdio.h", should be declared before they're used. (The type of each function in the C library is given in the chapter on the run time environment, below.) .# .SH "=incl=/ctype.h" This file defines the character testing macros discussed in the chapter on the run time environment. These macros are very useful, and are often faster than writing an explicit test (e.g. islower(c) should be faster than (c >= 'a' && c <= 'z')). The macros have been rewritten to only evaluate their argument [ul once], so that they won't bite you if the argument has side effects (.e.g. islower(*c++)). .# .SH "=incl=/swt.h" This file provides most of the functionality that the Ratfor programmer obtains from "=incl=/swt_def.r.i". Some of the Ratfor specific declarations have been deleted (for example, the "dynamic memory" routines). The programmer is referred to Appendix D of the .ul User's Guide for the Ratfor Preprocessor and the "swt.h" file itself for details. .pp One thing that may need clarifying: The SET_OF_?* macros are used in the following way: .be 10 [bl 4]. [bl 4]. switch (c = getchar()) { case SET_OF_UPPER_CASE: /* stuff for upper case */ break; case SET_OF_LOWER_CASE: /* stuff for lower case */ break; case SET_OF_DIGITS: /* stuff for digits */ break; default: /* stuff for default */ break; } [bl 4]. [bl 4]. .ee In other words, you supply the leading [bf case] and the trailing colon; the macro supplies everything else. .# .SH "=incl=/ascii.h" This file contains definitions for the ASCII mnemonics, as well as for the control characters. E.g. Both BEL and CTRL_G are defined as octal 0207. The synonyms BACKSPACE, TAB, BELL, RHT, and RUBOUT for other characters are also defined. .# .SH "=incl=/assert.h" This file defines the 'assert' macro. It must be specifically included in order to use it. See the chapter on the run time environment for what the 'assert' macro does. .# .SH "=incl=/debug.h" This file declares a macro "debug" which is useful for putting debugging code into your programs. For instance: .be #include ... debug (fprintf (stderr, "i == %d\n", i)); /* note the balanced parentheses */ ... .ee If the symbol "DEBUG" has been defined [ul before] is included, then whatever occurs as an argument to the "debug" macro will be placed into the source code. Otherwise, "debug" becomes a null macro. The easiest way to turn debugging on is to put "debug" statements in your code, and then do a "-DDEBUG" on the compiler command line. For larger blocks of code, you can do .be #ifdef DEBUG /* * a lot of debugging code */ #endif .ee .# .SH "=incl=/keys.h" This file declares the symbolic keys for the Primos file system. It is the analogue of "=incl=/keys.r.i". .# .SH "=incl=/lib_def.h" This file is analogous to the Ratfor include file "=incl=/lib_def.r.i". It contains symbolic constants and macros which are useful for dealing with the low level Software Tools Library routines. .# .SH "=incl=/math.h" This file contains declarations for all the mathematical routines in the C library. These routines all return [bf double]. .# .SH "=incl=/memory.h" This file contains declarations of mem?* functions. These functions are similar to the str?* functions, but work on arbitrary areas of memory, and do not care about the zero word, '\0'. This file should be included before using the functions, although you can always just declare each function before using it. .# .SH "=incl=/setjmp.h" This file [ul must] be included if you intend to use the 'setjmp' and 'longjmp' non-local goto functions. .# .SH "=incl=/swt_com.h" This file contains the necessary [bf #define]s and declarations for accessing the Software Tools common blocks from a C program. It has not been extensively tested. See the file for more details. .# .SH "=incl=/varargs.h" This file contains definitions which allow you to portably write functions which expect a variable number of arguments. The macros are discussed below, in the chapter dealing with the run time environment. They have not been extensively tested, but do seem to work. .# .MH "Loading C Programs For Bare Primos" Several of the routines in the C Library depend on the shared Subsystem libraries to do some of their work. .pp In order for you to write C programs to run under bare Primos, we have provided a second run time library with alternate versions of these few subroutines, as well as a second C start off routine. Most routines perform the same under both the Subsystem and bare Primos. Those few which behave differently under bare Primos are detailed in the chapter on run time facilities. In particular, they always return the value that indicates an error has occurred. .pp The alternate C start off routine and run time library are in the files =lib=/nc$main and =lib=/nciolib, respectively. Since loading programs for bare Primos is not simple, 'ld' does not have an option for loading C programs for running without the Subsystem. You must do it yourself, by hand. .pp To load a C program for use with bare Primos, follow this procedure: .rm -5 .in +5 .ta 4 .HI 3 1) Load the file =lib=/nc$main. This is the alternate startoff routine, which does some extra initialization. .HI 3 2) Load your C binaries. .HI 3 3) Load =lib=/nciolib. This library contains versions of the few routines which act differently under bare Primos. This library also contains a special version of 'getarg', to allow 'argc' and 'argv' to work properly. The environment pointer, 'envp' (see below), will be set to NULL when a program is loaded for running under bare Primos. .HI 3 4) Load =lib=/ciolib. This contains the rest of the C run time library. .HI 3 5) Load =lib=/vswtmath, if your C program uses the C math routines. .HI 3 6) Load =lib=/nvswtlib. This is the non-shared version of the Subystem library, which does most of the real work. .HI 3 7) Load any system libraries, e.g. the Fortran library. .sp .in -5 .rm +5 .ta .pp You should actually be able to use 'ld' to load your program, following this outline: .be ] [bf ld -dnu -l nc$main -l nciolib -l ciolib _] .bf [-l vswtmath] -l nvswtlb -t -m -o .ee .pp You will probably not have too many programs to be run under bare Primos, but we have provided for this possibility.