DECUS C LANGUAGE SYSTEM Compiler & Library Software Support Manual by Martin Minow Edited by Robert B. Denny This document describes the RSX/VMS/RSTS/RT11 DECUS C language system runtime support library. It also contains all internal functions and such compiler internal information as is available. DECUS Structured Languages SIG Version of 15-Oct-81  NOTE This software is made available without any support whatsoever. The person responsible for an implementation of this system should expect to have to understand and modify the source code if any problems are encountered in implementing or maintaining the compiler or its run-time library. The DECUS 'Structured Languages Special Interest Group' is the primary focus for communication among users of this software. UNIX is a trademark of Bell Telephone Laboratories. RSX, RSTS/E, RT11 and VMS are trademarks of Digital Equipment Corporation.  CHAPTER 1 INTRODUCTION The C support library contains three major groups of functions: o Functions called by the compiler to perform certain mathematical operations (such as floating-point multiply or function entrance) that are not performed in-line. o Functions that may be called by C programs to perform operations, such as copying a string, that are more efficiently performed by optimized assembly language subroutines. o An implementation of (most of) the Unix Standard I/O library. The standard installation procedure yields two documents. The Runtime Support Library Reference Manual describes how to use the C library. The Compiler and Library Software Support Manual contains all user documentation plus additional information on the internals of both the library and the C compiler. This is the Software Support Manual.  CHAPTER 2 THE STANDARD LIBRARY WARNING This version of the library is somewhat incompatible with previous versions of the Decus C compiler. This incompatibility allows greater compatibility with Unix Version 7, and the capability of generating global references and definitions containing the radix-50 '$' and '.' characters. All C programs should be linked together with the run-time support library. On systems that support logical device descriptors, this will generally be stored in the C: logical device/account. On RSX-11M, the library will be found in LB:[1,1]. To link a C program, proceed as follows: RSX TKB TKB> task/CP,map=objects,LB:C/LB TKB> / ENTER OPTIONS: TKB> STACK=2000 TKB> // RT11 R LINK *save,map=objects,C:SUPORT,C:CLIB/B:2000 *^C Note that, on RSX-11M, the task should be built checkpointable. This is automatic on RSTS/E and VMS emulated modes. On native RSX-11M, the task-builder may be rebuilt with '/CP' as the default. If the '/CP' switch is not given, the task may abort (no memory) when started. Stack extension is needed if subroutines locally allocate large amounts of data. On RT11, note that the '/B' (bottom) switch must be given to increase the size of the run-time stack. This is needed as local variables are allocated on the stack. If the stack size  C Compiler and Library Page 2-2 Software Support Manual is not increased, the program may abort without any error message. The standard I/O interface header file is in C:STDIO.H (LB:[1,1]STDIO.H on native RSX-11M implementations) and should be included in all C programs as follows: #include 2.1 Introduction to Unix-style Stream I/O ____________ __ __________ ______ ___ This section presents an overview of the 'standard' I/O interface for C programs. These routines have proven easy to use and, while they do not provide the full functionality of RSX or RMS, they give the programer essentially all that is needed for everyday use. The discussion includes the following: - Opening and closing files - Reading data from files - Writing data to files Note that this file system is limited: files are sequential with only a limited amount of random-access capability. Also, little of the power of RMS/FCS is available. On the other hand, the limitations make C programs easily transportable to other operating systems. When a C program is started, three files are predefined and opened: stdin The 'standard' input file stdout The 'standard' output file stderr The 'standard' error file Stderr is always assigned to the command terminal. Stdin and stdout are normally assigned to the command terminal, but may be reassigned or closed when the program starts. 2.2 Opening and Closing Files _______ ___ _______ _____ The fopen and fclose functions control access to files. They are normally used as follows: #include /* Define standard I/O */ FILE *ioptr; /* Pointer to file area */ ... if ((ioptr = fopen("filename", "mode")) == NULL) error("Can't open file");  C Compiler and Library Page 2-3 Software Support Manual All information about an open file is stored in a buffer whose address is returned by fopen(). The buffer is dynamically allocated when the file is opened and deallocated when the file is closed. Its format is described under the heading IOV. The mode string contains flags defining how the file is to be accessed: r Read only w Write new file a Append to existing file (or write new) (Doesn't work on RT11 modes). It also defines some record-control information: n No newlines mode ('binary' files) u RSX: The user program allocates record buffers RT11: Console output is done using .ttyout If mode 'n' is specified, the RSX I/O routines do not interpret the end of a RMS logical record as defining the end of a human-readable line. This is necessary to process 'binary' information. On RT11, the I/O routines do not remove carriage-returns from input files, nor do they insert carriage-returns when newlines are output. Mode 'u' is treated differently on RSX and RT11. If specified on RSX the user maintains the file's record buffer. The program may only call the fget() and fput() routines. Each such call will be translated directly to an RMS/FCS GET$ or PUT$ call. (In RT11 mode, fput() may be used to write binary records which are subsequently read by fget(). The file should be opened with 'n' mode.) If mode 'u' is specified on RT11 mode when opening the console terminal, single character output will be performed (using the RT11 monitor routine .ttyout). If not specified, output will be one line at a time (using the monitor routine .print). The library initialization process opens stderr in mode 'u' and stdout in normal mode. This means that mixing I/O to both units will result in synchronization problems. To obtain single-character output on stdout, the program need simply execute: if (freopen("tt:", "wu", stdout) == NULL) error(""); The program calls fclose(ioptr) to terminate processing on a file. This closes the file and reclaims system-controlled buffer space. fmkdl(ioptr) may be called to close and delete an open file.  C Compiler and Library Page 2-4 Software Support Manual 2.3 Reading Data from a File _______ ____ ____ _ ____ The simplest way to read a file is to call the getchar() or getc() routines which read the next character from a file. For example, the following program counts the number of characters in a file: #include main() { register int ccount; register int lcount; register int c; FILE *ioptr; if ((ioptr = fopen("foo.bar", "r")) == NULL) error("Cannot open file"); ccount = 0; lcount = 0; while ((c = getc(ioptr)) != EOF) { ccount++; if (c == '\n') lcount++; } printf("%d characters, %d lines.\n", ccount, lcount); } Other input routines include: gets Read a line from the standard input fgets Read a line from a file fgetss Read a line from a file, remove terminator ungetc Push one character back on a file fseek Position the file to a specific record These routines are used together with the ferr() and feof() functions which allow testing for error and end of file conditions, respectively. The package assumes that all error conditions are lethal and force end of file. 2.4 Writing Data to a File _______ ____ __ _ ____ There are several routines for data output which are directly analagous to the data input routines: putchar Write a character to standard output putc Write a character to a specified file puts Write a string to the standard outpt fputs Write a string to a specified file fputss Write a record to a specified file ftell Return record location (for fseek) In addition, the printf() or fprintf() routine is used to format  C Compiler and Library Page 2-5 Software Support Manual and print data (as was shown in the previous example). Printf() is flexible, powerful, and easy to use; and is perhaps the single most important routine in the file system. 2.5 Interaction with the Operating System ___________ ____ ___ _________ ______ The support library attempts to provide a consistant operating system interface on several implementations of quite different operating systems. The possiblities include: o Native RT11 o Native RSX-11M or IAS o RT11 emulated on RSTS/E o RSX-11M emulated on RSTS/E o RSX-11M emulated on VAX/VMS This section mentions the inconsistencies and random bugs that are more or less intentionally present. 2.5.1 Logical Unit Numbers _______ ____ _______ RT11, RSTS/E, and RSX-11M use small integers to number all I/O channels. Unfortunately, the numbering is not consistent and channel usage differs among the various systems. This has resulted in several quirks: o On RT11, console terminal interaction uses the .ttyout and .print monitor functions. While no device is opened by the fopen() function, a channel number is reserved. o On RSX-11M, a channel must be allocated to the console terminal. When a C program starts, the 'command terminal' is opened on logical unit 1 and assigned to stderr. This is not done using the fopen() routine (although the stderr IOV structure is defined as if fopen() were called). Also, fclose() cannot close stderr. In addition to the standard I/O routines, there are two routines, msg() and regdmp(), that direct output to logical unit 1. These routines were used to debug the library, and are otherwise useful for disasters. On RT11, msg() and regdmp() use the .print monitor function.  C Compiler and Library Page 2-6 Software Support Manual o On both systems, the first true files are stdin and stdout. These are opened on logical units 0 and 1 (RT11) or 2 and 3 (RSX). Code in fclose() double-checks that the logical unit number of the file being closed corresponds to the proper slot in the logical unit table. o Since the standard I/O routines know little about the operating system, they do not deal with certain special features. For example, on RT11, the 'user service routine' (USR) is used to open files. The file open routine does not attempt to locate IOV areas so that the USR does not swap over them. This can be a problem for very large programs. On RSX, logical unit numbers are assigned dynamically. This means that 'LUN assignment' cannot be reliably performed by task-build control files (or task initiation). 2.5.2 Wild-Card Files _________ _____ The fwild() and fnext() routines can be used to process 'wild-card' files. On RSX-11M and VMS/RSX emulation, the file name, extension, and/or file version may be expressed as '*' to indicate wild-card support. Due to restrictions in the RSX-11 Files-11 structure (ODS1), the ' ', ';0' and ';-1' version numbers will NOT function properly on native RSX-11. This means that '*.MAC' will not work, for instance. The algorithm in fwild() depends on the directory being sorted, as in the ODS2 file structure used on VAX/VMS. If you sort the directory to be used in an fwild() operation (use the SRD program available from DECUS with the /WB switch) in order of decreasing file version numbers, then the " ", ";0", and ";-1" versions will work. Wild-card devices, units, or UIC codes are not supported. Note that, on RSX11 emulated on VMS, the ';-1' (earliest version) requires special processing by the user program, as noted in the description of fwild(). On RSX-11M emulated on RSTS/E, the file name and/or extension may contain '*' or '?' wild-cards. Wild-card devices, units, or UIC (PPN) codes are not supported. On RT-11, the file name and/or extension may contain '*', '%' or '?' wild cards. The '?' wild-card is synonymous with '%'. Wild-card devices, or units are not supported. Since wild-card  C Compiler and Library Page 2-7 Software Support Manual support is not an RT-11 system service, the file specification parsing and directory operations are handled by the C library fwild() and fnext() functions. The fwild/fnext module requires about 480 words of storage. Also, a file opened by wild-card uses a 1024 byte buffer, twice the normal size, which is shared between data and directory operations. 2.5.3 Memory allocation ______ __________ Memory is allocated using the malloc() function. It works correctly on all operating systems, expanding memory on RSX and RT11/RSTS. On 'native' RT11, all available memory is allocated by invoking the monitor .settop function with a '-2' argument. Neither library supports extended memory (PLAS) directives. The sbreak() routine may be used for permanent allocation of memory. Once memory has been allocated using sbreak(), it cannot be freed. 2.5.4 Global symbols ______ _______ Global symbols defined or referenced by C programs may cause unexpected parts of the operating-system support library to be loaded, with undesirable consequences. There are several aspects to this problem: o A symbol refered to by a C program which is not resolved by the object modules or libraries may cause some part of the system library to be loaded. For example, if a C program refers to the sqrt() function (which is not present in the standard library), the linker may attempt to load the function from the Fortran library. Since the Fortran sqrt() function contains a reference to the Fortran run-time error message routine, the load map may contain many strange global symbols. o Another problem occurs when a C program defines a global symbol that duplicates a global in the system library. This may prevent loading some necessary part of the system library, causing the link to fail with unresolved global symbols. For example, on RSX-11M emulated on RSTS/E V7.0, the following will fail: int eof; /* Global */ main () { }  CHAPTER 3 SUPPORT INFORMATION The C system has been implemented on VMS V2.0, RSX-11M V3.2, RSTS/E V7.0, and RT11 V03B. All installations should expect to have to modify the command procedures to suit their specific needs. While the compiler has been built from scratch on RT11, the procedures unrealistically assume a system with no disk storage limitations. The C system has not been tested on IAS, RSX11-D, RSX11M-PLUS, or HT11. The C system is distributed on 9-track magtape in 'DOS-11' format. The full distribution requires a 2400 foot (or three 600 foot) tapes. Please Note This is a DECUS 'product'; there is no support available from the authors. The person responsible for an implementation of this system should expect to have to understand and modify the source code if any problems are encountered in implementing or maintaining the compiler or its run-time library. The DECUS 'Structured Languages Special Interest Group' is the primary focus for communication among users of this software. This section contains information on the internals of the compiler, assembler, and run-time libraries. It is not complete; it is probably not accurate either. 3.1 The C Compiler ___ _ ________ The compiler source is distributed on account [5,3]. There are four groups of files in this account: o The C compiler source is in modules named CC???.MAC. The root code is in CC0RT.MAC, while overlays are in CC00?.MAC, CC10?, CC20?, and CC3??. The overlays have the following functions:  C Compiler and Library Page 3-2 Software Support Manual 0. Pass 0 reads the input source file, writing a temporary file after processing #define, #include, and #ifdef statements. 1. Pass 1 reads the expanded source file, parses the language and writes an 'intermediate code' file. In the intermediate file all operations have been converted into 'low-level' constructions. Variable and structure references are compiled into absolute expressions. All information needed by the code generator is contained in this file. Except for compiler flags and file names, nothing is retained in memory. 2. Pass 2 reads the code file, writing PDP-11 assembly language (in the format requested by the AS assembler). 3. Pass 3 contains some end of processing code to delete work files. All internal files are in Ascii. In order to make the compiler portable between RSX, RSTS/E, and RT11, the file system is simple and inefficient. RT11 users may run into intermediate file size problems. The only (software) solution requires invoking the compilation with explicit size arguments for the output files: #out.s[N1],interm.tm1[N2],expand.tmp[N3]=in.c The expanded source file should be less than the size of the input file plus all #include files. The intermediate file size may be as much as twice the size of the expanded source file. o C programs are assembled into PDP-11 object code by the AS assembler, whose source files are named 'AS????.MAC'. The AS assembler is described in AS.DOC. o A support library for the two compilers is included in a group of files labeled A?????.MAC. The C compiler build process also builds the support library. This library is similar -- but not identical -- to the run-time support library. The compiler and assembler are installed by executing command files. There are several groups of command files supplied to assist in implementation on the various operating systems. It is highly likely that the files will have to be edited to suit each individual installation's needs. VMS, RSX, and RT11 files are run by the indirect command file processor, while RSTS/E files are run by the ATPK system program. RSTS/E installation requires must be run from a privileged account.  C Compiler and Library Page 3-3 Software Support Manual The following file conventions are used: VMS command files begin with the letter 'V', RSTS/E RT11 mode with the letter 'R', and RSTS/E RSX mode with the letter 'X'. Native RT11 command files begin with 'T' and native RSX-11M files begin with the letter 'M'. Thus, XMAKCC.CMD builds the CC compiler for RSTS/E RSX-11M mode. The '.TKB' files are indirect command files for the task-builder. Warning As distributed, the compiler and run-time libraries assume hardware support for the SXT (sign-extend) instruction. This is present on all PDP-11 CPU's with EIS, and on all versions of the LSI-11 (11/03, LSI-11, 11/23). If the compiler is to generate code that will run on the 11/04, 11/05, 11/10, 11/20, or on an 11/40 without EIS; all RSX.MAC and RT11.MAC configuration files must be edited to define symbol C$$SXT equal to zero. Note that the compiler must be build with C$$SXT set correctly. As distributed, the RSX configuration files assume hardware EIS support. If this is not the case (hardware EIS is not needed for RSX-11M) edit the RSX.MAC control files to define symbol C$$EIS equal to zero. There are two RT11 configuration files, and the RSTS/E library build procedure builds an EIS library, CLIB.OBJ, as well as a library without EIS support, CLIBN.OBJ. The default 'native' RT11 command file builds a non-EIS library, naming it CLIB.OBJ. Programs linked against the non-EIS library will run on machines with EIS. Also, save-images linked on RT11 will run on RSTS/E and vice-versa without relinking. There are certain differences in task-image format between native RSX-11M and RSX-11M as emulated on RSTS/E. Thus, only source or object files are transportable between the two operating systems. 3.2 The C Run-time Support Library ___ _ ________ _______ _______ The C support library is distributed on two accounts, [5,4] and [5,5]. Account [5,4] contains only those routines which have no I/O dependencies, while account [5,5] contains the standard I/O library. Many routines are conditionally compiled to select RT11 or RSX mode. All routines should be compiled together with either  C Compiler and Library Page 3-4 Software Support Manual RT11.MAC (no EIS support), RT11.EIS (hardware EIS support), or RSX.MAC, identical copies of which are present in each account. To build the libraries, execute one of the following command files: RMAKLB.CMD RT11 library on RSTS/E VMAKLB.COM RSX library on VMS XMAKLB.CMD RSX library on RSTS/E MMAKLB.CMD RSX library on RSX-11M TMAKLB.COM RT11 library on RT11 Account [5,1] contains a program, GETCMD.C which was used to build assembler command files. On RSTS/E, a command file, [5,1]RLBCMD.CMD, may be used to rebuild all library command files. All library source code is in PDP-11 MACRO. 3.3 The RSTS/E Interface Library ___ ______ _________ _______ Account [5,6] contains a library of subroutines that allow C programs access to all RSTS/E executive functionality. There is no documentation other than the source code and [5,6]README.506. 3.4 The RSX-11 Extensions Library ___ ______ __________ _______ Account [5,7] contains a library of subroutines that allow C programs access to all RSX-11M executive functionality, including AST's. Refer to [5,7]CX.DOC for more information. This library has not been completely tested, nor has it been tested on 'emulated' RSX-11M modes (under VMS or RSTS/E), nor on IAS or RSX11-PLUS. 3.5 RT11 Extensions Library ____ __________ _______ Access to RT11 executive functionality may be had by calling the system library (SYSLIB). The C library call() routine may be used to generate the necessary calling sequences. Note that SYSLIB routines that depend on Fortran I/O conventions must not be called.  C Compiler and Library Page 3-5 Software Support Manual 3.6 C Tools and Toys _ _____ ___ ____ The distribution kit contains several accounts [6,*] with C programs and subroutines. Account [6,1] contains a library of 'software tools' which should be useful for all C installations. Among these are the following: echo Echo arguments onto the standard output. This program serves as the primary test of the run-time library. grep 'Get regular expression pattern.' This program reads one or more files, printing text lines that match a given pattern. kwik 'Key word in context' utility. sortc A file sort utility. sorts Sort-merge subroutines for incorporation into other programs. wc Count bytes, words, and lines in one or more files. ccxrf Cross-referenced listings for C source files. Please refer to README.??? files in the appropriate accounts for more information. 3.7 Building the Documentation ________ ___ _____________ Compiler and assembler documentation is in CC.RNO and AS.RNO respectivly. These files, stored in [5,1] or [.COMMAND], are compiled into .DOC files by using Runoff. The documentation build control file appends the current problem list CBUGS.RNO to CC.RNO before building the documentation. NOTE In order to create titles properly on VMS "Standard Runoff," a command line is present which may cause a non-fatal error message to be printed by other versions of Runoff, notably RNO.TSK. This error message should be ignored. The source of the library documentation is included within the library source (Macro) files.  C Compiler and Library Page 3-6 Software Support Manual To build the library documentation, the following programs must have been built and installed on the system: getrno This program reads the library header file, breaking out wizard and non-wizard sections. It then reads a set of macro files (specified using a wild-card convention). Each file contains its own documentation in the form of commentary. This follows a specific, rigid format as described in the documentation of getrno.c. The output of getrno is a runoff source file which is then merged with the various appendices to the library documentation. The source of getrno.c is stored in [5,1] or [.COMMAND]. The running program is normally stored in C:. getkwk This program reads the library macro files, searching for "Index" entries in the documentation. The output of getkwk is passed directly to kwik. The source of getkwk.c is stored in [5,1] or [.COMMAND]. The running program is normally stored in C:. kwik This is the keyword in context program which is used to build the library index. It is built as part of the tools build procedure. The source of kwik.c is stored in [6,1] or [.TOOLS]. The running program is generally written to a public library, PUB: on RSTS/E, BIN: on VMS. fixdoc On RSTS/E RNO.TSK and VMS "Standard RUNOFF", page numbers are put at the "page right margin" (column 80) instead of the text right margin, column 72. As a workaround, getrno is used to mark runoff .title lines. Fixdoc is then run to straighten out the titles. Note that this is needed for RSTS/E RNO and VMS RUNOFF only. The source of fixdoc.c is stored in [5,1] or [.COMMAND]. The running program is noramlly stored in C:. Note that is is used only on ____ RSTS/E. The control files [5,1]RGTRNO.CMD and [5,1]RGTDOC.CMD illustrate the process on RSTS/E while VGTRNO.COM and VGTDOC.COM illustrate it on VMS.  CHAPTER 4 COMPILER INTERNAL INFORMATION As noted above, compiler work files are in human-readable Ascii. The parser generates a temporary file with an internal pseudo-code. The code generator converts this pseudo-code to PDP-11 assembly language. Except for compiler flags, all communication between passes is via intermediate files. 4.1 Intermediate Code File Format ____________ ____ ____ ______ The intermediate code file consists of single line entries for each operation. The first byte is an operator, followed by parameter entries as needed. Numeric values are transmitted in octal. The following operators are defined: Location counter control: C Switch to the string P-section (c$strn) O Switch to the data P-section (c$data) P Switch to the program P-section (c$code) Ux[name] [attr] Define program section (x == P or D) Flow control: L [number] Define a local label J [number] Jump to a local label X Function exit N Function entry Data reservation, etc.: A Generate a .even pseudo-op B [number] Generate a .blkb [number] D Generate an external label G Generate a .globl H Generate a .byte I Generate a .word as a local pointer Y Generate a .word Special operations: @ No-op: generate a comment W Generate a switch table Q Dump symbol table entry (-t switch)  C Compiler and Library Page 4-2 Software Support Manual M Transmit a line number between passes Tree (expression) operators: R Return S Switch E Compile for effect T Jump if true F Jump if false K Initialize variable Z Tree item Note that 'trees' are the result of compiling expressions, such as (a + b * (c & 4)) * d Each non-terminal node of a tree generally consists of a left part, an operation, and a right part. Operator precedence has been resolved. The above example thus becomes: | ------------------ | | --------- | | | | | -------- | | | | | | | ----- | | | | | | ((a + (b * (c & 4))) * d) Trees are described by 'Z' records. Tree elements are variable-length records, the first value describing the operator (and, hence, the length). All numeric values are encoded as octal ascii strings. The tree types are as follows: OP.EOF Used to signal a null tree element. OP.CON Constant, followed by 4 values. OP.REG Register, followed by type and register number. OP.INX Offset from register, followed by type, register number, and offset value. OP.ID Global identifier, followed by type, and identifier name. OP.LID Local identifier (label), followed by number. other An operator (OP.ADD, etc.) followed by the type code. Subsequent records contain the left subtree, then the right subtree. (OP.EOF is used to signal a null subtree.)  C Compiler and Library Page 4-3 Software Support Manual For example, here is a simple subroutine and the intermediate code it generates (the trees have been compressed): fact(n) D fact | define function fact { N 0 4 | enter function if (n == 0) F 1 | if false, goto L1 Z [n == 0] | compile expr. value return(1); R | return Z [1] | compile expr. value J 2 | goto L2 return(n * fact(n - 1)); L 1 | Label L1, N != 0 R | return Z [n * fact(n - 1)] | compile expr. value L 2 | label L2 } X | Exit from function G fact | .globl fact The C source code is parsed by a top-down, recursive parser. Expressions are parsed bottom-up, by priority. Casts of types are processed by special routines. The parser does some optimizations, such as constant folding. Also, all automatic variables (local to a function), are assigned absolute offsets from the argument frame (Register 5), while structure elements are assigned absolute offsets from the base of the structure. 4.2 The Code Generator ___ ____ _________ The code generator consists of a top-level input file reader, which processes 'easy things' directly. It calls subroutines to compile switch statements and expressions. The expression compiler performs various optimizations, calls a Sethi-Ullman register allocator, then a code generator. The Sethi-Ullman algorithm was described in the Journal of the ACM, Volume 17, No. 4, October 1970. pp. 715-728. 4.2.1 Optimizations and Register Allocation _____________ ___ ________ __________ The following optimizations are performed: o Expressions are reordered. o Constant expressions are folded. o Dummy operations are eliminated, including -(-A), !(!A), ~(~A), (A & A) and (A | A). o Dummy address expressions are eliminated: *(&A) and  C Compiler and Library Page 4-4 Software Support Manual &(*A) all become A. o Constant address arithmetic is performed in expressions such as &A + const. o Constant offsets from registers become index operations in expressions such as *(reg + constant) or *(reg - constant). o PDP11 autoincrement and autodecrement are used in expressions such as *p++ and *--p. o Conversion between integer and pointer datatypes are converted to multiply and divide operations. o Multiply by 1 is deleted. o The and operator is converted to BIC. o Null operations are deleted, including +0, -0, &-1, |0, ^0, |=0, etc. o If the compiler has been built for in-line floating point (i.e., the machine on which the compiler runs supports floating point), floating point constants are folded. Register allocation is as follows: o R0 and R1 are always scratch registers. o R2, R3, and R4 may be reserved by the C program by using the 'register ...' construction. The parser tells the coder the highest register it can use (in the function initialization intermediate code operation). o The Sethi-Ullman algorithm stores the number of registers needed into each tree node. This number is always >= 2 to insure that R0 and R1 are available for scratch usage. o 'A tree is easy if the other tree uses few enough registers and there is a free register available.' o The GETREG subroutine claims registers. If the code table is modified, be sure that GETREG isn't called on a tree that isn't easy.  C Compiler and Library Page 4-5 Software Support Manual 4.2.2 Code generation ____ __________ Almost all code is generated by expanding macro operators out of the code tables. There are four tables (CTAB, ETAB, STAB, RTAB) and a pseudo-table, TTAB. Only RTAB is complete, If an expansion which was attempted in CTAB or ETAB fails, it is retried in RTAB followed by a test (CTAB), move (ETAB), or push (STAB) operation. For example, if an expansion which was attempted in STAB fails, it is done by: [Rtab] mov Reg,-(sp) The code body is in Ascii; bytes with the parity (eighth) bit set are used macro operators: 'address of left', 'push right', etc. Code table entries are selected by the type of the arguments (int, char, long, unsigned, float, double, and pointer) and by kind (constant, address, easy, and any). Here is a typical code table (for addition): int any int con1 ; Add 1 to any integer [LL] ; Compile left (subtree) inc [R] ; INC Rx int any int addr ; Add var. to anything [LL] ; Compile left (subtree) add [AR],[R] ; ADD var,Rx int any int easy [SRV] ; Setup right value, ; NOP if it's an address [LL] ; Compile left (subtree) add [AR],[R] ; Add var,Rx int any int any [PR] ; Compile right to stack [LL] ; Compile left to reg. add (sp)+,[R] ; ADD (sp)+,Rx Here is another example, '= for effect' (as in 'A = B;'): int any int con0 ; I = 0; char any int con0 ; C = 0; [SLAC] ; Get left op. address clr[TL] [AL] ; CLR(B) var int addr int any char addr int any [LR] ; Compile right subtree mov[TL] [R],[AL] ; MOV(B) Rx,var  C Compiler and Library Page 4-6 Software Support Manual int any int easy char any int easy [SRV] ; Setup right value [SLAC] ; Setup left address mov[TL] [AR], [AL] int any int any char any int any [PLA] ; Push left address [LR] ; Compile right value mov[TL] [R],@(sp)+ Note that the "easy" storage will handle indirect addressing "(rx)", as well as autoincrement "@(rx)+" and autodecrement "@-(rx)". If the datum is long, the and code operators perform the address computation without side-effects. For example, the following computation performs "i <<= 8", where 'i' is an integer: swab [ALN] clrb [ALN] mov [AL],[R] 4.2.3 Macros used in code generation ______ ____ __ ____ __________ The following are defined in the code generator: [M] Set modulo return [F] Set function return [F.1] Result value is in r1 [R] Current register [R.1] Current register + 1 [AL] Address of left [AL.2] Address of left+2 (long int) [AL.4] Address of left+4, double [AL.6] Address of left+6, double [ALN] Address of left, no side effect [AR] Address of right [AR.2] Address of right, long [ARN] Address of right, no side effect [OP.0] Opcode [OP.1] Opcode [TL] Type of left [T] Type of right or left [SRVA] Set right value anywhere [SRV] Set right value [SRAA] Set right address anywhere [SRA] Set right address [SLVA] Set left value anywhere [SLV] Set left value [SLAA] Set left address anywhere  C Compiler and Library Page 4-7 Software Support Manual [SLA] Set left address [SLAC] Set left address current reg. [LL] Load left [LL.1] Load left into [R+1] [LL.O] Load left into odd register [LLP.O] Load left into odd of pair of registers [LLP.E] Load left into even of pair or registers [LR] Load right [LRP.E] Load right into even of pair of registers [PL] Push left [PLA] Push left address [PR] Push right [V] ADC or SBC for longs [FPI] Set floating point to I mode [FPL] Set floating point to L mode [FPF] Set floating point to single precision [FPD] Set floating point to double precision [GO.TO] Branch within code table [IFEIS] Compile if hardware EIS support [IFFPU] Compile if hardware FPU support [IFOP] Compile if specifed opcode [ELSE] Compile if IF... test was false [ENDIF] End IF... block [DEBUG] Write debug record to .S file  CHAPTER 5 LIBRARY FUNCTION DESCRIPTIONS This chapter contains descriptions of each of the C-callable runtime library functions. In addition, descriptions of internal routines are provided. In most cases the I/O functions match those of UNIX V7 closely, with differences normally called out. For more information, consult "The C Programming Language" by Brian Kernighan and Dennis Ritchie (Englewood Cliffs, NJ: Prentice-Hall, ISBN 0-13-110163-3). Routines and global symbols beginning with '$$' are used for communication among the I/O routines. Routines whose names are of the form 'ABC$X' implement the 'ABC' instruction for the 'X' data type. For example, 'ASL$LI' implements an arithmetic left shift of a long value by an integer argument.  C Compiler and Library Page 5-2 $$abuf Allocate memory for i/o buffers 5.1 Allocate memory for i/o buffers ________ ______ ___ ___ _______ ********** * $$abuf * ********** File name: ioabuf.mac Usage mov #iov,r4 ;file data block call $$abuf ;Allocate it bcs error ;Exit on errors Description A block of memory is allocated. If it succeeds, the iov record buffer is correctly setup and $$abuf returns the buffer address in r0. If it fails, an error code is stored in $$ferr, the error bit set in the iov flag word, r0 is set to 0, and $$abuf returns with the C-bit set. In RSX mode, the record gets padding that may be needed by $$put. Bugs  C Compiler and Library Page 5-3 $$c5ta Convert Radix-50 to Ascii 5.2 Convert Radix-50 to Ascii _______ ________ __ _____ ********** * $$c5ta * ********** File name: c5ta.mac Usage mov rad50_word, r1 mov out_ptr, r0 call $$c5ta Return: r0 updated r1 random other registers preserved. Description: Convert one radix-50 word to three Ascii bytes. All letters will be in upper-case. The output buffer will not be null-trailed, nor will blank fields be supressed. Bugs  C Compiler and Library Page 5-4 $$cl16 Close all channels 5.3 Close all channels _____ ___ ________ ********** * $$cl16 * ********** File name: iocl16.mac Usage $$cl16(); /* Close all channels */ Description This module closes all I/O channels. It is called on exit from C programs. Diagnostics Bugs  C Compiler and Library Page 5-5 $$clfu Flush last record before closing 5.4 Flush last record before closing _____ ____ ______ ______ _______ ********** * $$clfu * ********** File name: ioclfu.mac Usage mov #iov,r4 ;r4 -> i/o vector call $$cflu ;Flush buffers for close Description Flush the output buffer if the file is open for output. On RSX, the code may be conditionally compiled so that the last buffer is fixed so it is SEE compatible. Bugs  C Compiler and Library Page 5-6 $$ctim Convert $$rtim Buffer to Ascii 5.5 Convert $$rtim Buffer to Ascii _______ ______ ______ __ _____ ********** * $$ctim * ********** File name: rctime.mac Usage char * $$ctim(buffer); struct TIME { int year; /* G.TIYR year - 1900 */ int month; /* G.TIMO Jan. = 1 */ int day; /* G.TIDA */ int hour; /* G.TIHR 00 .. 23 */ int minute; /* G.TIMI 00 .. 59 */ int second; /* G.TISC 00 .. 59 */ int tick; /* G.TICT 00 .. tsec-1 */ int tsec; /* G.TICP tick/second */ } buffer; dayofweek(buffer); struct TIME buffer; Description $$ctim() converts the time information in buffer such as returned by $$rtim() to a character string in the format: Sun Sep 16 01:03:52 1973\0\0 All the fields have constant width. Note that there are two trailing 's for the benefit of programs converted from Unix (where the year is followed by a ). $$ctim(0) returns the current time of day, calling $$rtim() internally. The format of the returned information is identical to the Unix function of the same name except that the Unix function has a trailing newline which is omitted here. dayofweek() returns the day of the week (Sunday = 0) for the date information in the argument buffer.  C Compiler and Library Page 5-7 $$ctim Convert $$rtim Buffer to Ascii Bugs There is no range checking on the information passed.  C Compiler and Library Page 5-8 $$div2 Unsigned divide (Macro only) 5.6 Unsigned divide (Macro only) ________ ______ ______ _____ ********** * $$div2 * ********** File name: div2.mac Usage mov hi_div,r0 ;High-order dividend mov lo_div,r1 ;Low-order dividend mov divisor,r2 ;Divisor jsr pc,$$div2 ;Perform the division mov r0,hi_quotient ;High-order quotient mov r1,lo_quotient ;Low-order quotient mov r2,remainder ;Remainder Description Perform an unsigned double-precision division. This is needed for one of the library conversion routines. Bugs  C Compiler and Library Page 5-9 $$dtoa Convert floating to ASCII 5.7 Convert floating to ASCII _______ ________ __ _____ ********** * $$dtoa * ********** File name: dtoa.mac Usage char * $$dtoa(buff, conv, field, dplace, value) char *buff; /* Where it goes */ char conv; /* Conversion type */ int field; /* Maximum field width */ int dplace; /* Decimal part width */ double value; /* What to convert */ Description $$dtoa() is called to do the conversion to Ascii The text is written to buff[]. $$dtoa() returns a pointer to the trailing null byte. Field and dplace are the conversion parameters "f" and "d" in the format string "%f.df". Conv is 'e', 'f', or 'g' to define the format. Note that the conversion character must be in lower-case. $$dtoa() is called by printf to convert a double-precision value to Ascii. The text is written to buff[]. Field and dplace are the conversion parameters "f" and "d" in the format string "%f.df" Conv is 'e', 'f', or 'g' to define the format. Note: the conversion character must be in lower-case. To use floating point conversion, the program must reference the $$fpu global as follows: extern int $$fpu; If this is not done, attempting to convert floating point will result in your program crashing. Bugs Only single precision conversion is done so far. The machine must support FPU floating point, which  C Compiler and Library Page 5-10 $$dtoa Convert floating to ASCII implies EIS. No compile-time test for C$$EIS is done. Note: This routine uses the table in the DOUTAB module  C Compiler and Library Page 5-11 $$fadd Floating-point support, add/subtract 5.8 Floating-point support, add/subtract ______________ ________ ____________ ********** * $$fadd * ********** File name: fadd.mac Usage double $$fadd(a, b) /* Floating add a + b */ double $$fsub(a, b) /* Floating sub a - b */ double a; double b; Description Called by the compiler to compile floating-point. Bugs BEWARE: Untested  C Compiler and Library Page 5-12 $$falo Allocate memory for i/o subroutines 5.9 Allocate memory for i/o subroutines ________ ______ ___ ___ ___________ ********** * $$falo * ********** File name: iofalo.mac Usage mov size,r0 ;Memory needed call $$falo ;Allocate it ;return, r0 -> allocation ;no room: return to caller via $$fope Description A block of memory is allocated. If this fails, the return is to the caller of fopen (or fwild/fnext) with i/o control blocks deleted as necessary. Bugs  C Compiler and Library Page 5-13 $$fcsi Scan file name for fopen 5.10 Scan file name for fopen ____ ____ ____ ___ _____ ********** * $$fcsi * ********** File name: iocsi.mac Usage mov iov,r4 ;r4 -> iov call $$fcsi ;C$PMTR+0(r5) => file name ;file name is parsed and fdb setup. ;r0-r3 random ;error: return to caller via $$fope Description Parse the file name argument, initializing the file data block. Used on RSX only. Bugs  C Compiler and Library Page 5-14 $$flsh Flush output buffers 5.11 Flush output buffers _____ ______ _______ ********** * $$flsh * ********** File name: ioflsh.mac Usage mov #iov,r4 ;r4 -> i/o vector call $$flsh ;Internal flush routine Return, all registers preserved. Description $$flsh is called by other file I/O routines to flush the current record buffer. If this is the first call to an output routine for this file, $$flsh will be called and will allocate a buffer. On RSX, if the file is open to the "command terminal", the flush is to stderr. Bugs  C Compiler and Library Page 5-15 $$flun Allocate a logical unit for fopen 5.12 Allocate a logical unit for fopen ________ _ _______ ____ ___ _____ ********** * $$flun * ********** File name: ioflun.mac Usage mov iov,r4 ;r4 -> iov if any, else r4 := 0 call $$flun ;Get a Lun slot, initialize fdb ;return, r4 -> iov, r3 := lun ;r0, r1 random ;error: return to caller via $$fope ;Note: available RSX luns start at 2, ;while RT11 luns start at zero. Description Perform all initialization needed to allocate a new file descriptor. Bugs In RSX modes, the maximum number of files that may be simultaneously open is defined at assembly time by a macro (FSRSZ$) which is expanded when fopen.mac is assembled. The default FSRSZ$ parameter is 4. This may be modified by using the task builder /ACTFIL=n option. The default FSRSZ$ value may be specified when the RSX library is built by editing assembly parameter N$$FIL in RSX.MAC.  C Compiler and Library Page 5-16 $$fmul Floating-point multiply/divide 5.13 Floating-point multiply/divide ______________ _______________ ********** * $$fmul * ********** File name: fmul.mac Usage double $$fmul(a, b); /* Floating multiply */ double a; double b; Description Called by the compiler to execute floating-point multiply. Bugs BEWARE: untested  C Compiler and Library Page 5-17 $$fopa Open file (RT11 only) 5.14 Open file (RT11 only) ____ ____ _____ _____ ********** * $$fopa * ********** File name: iofopa.mac Usage mov iov,r4 ;r4 -> iov mov lun,r3 ;r3 := lun jmp $$fopa ;RT11 file open (ascii file spec.) ;C$PMTR+0(r5) => ASCII file spec. ;(may include file size for writes) ;Parse the file using .CSISPC, open it, ;returning to the caller via cret$ or ;$$fope if error. mov iov,r4 ;r4 -> iov mov lun,r3 ;r3 := lun mov dblk,r1 ;r1 -> Rad50 device descriptor, followed ;by filesize word if write reqeust. jmp $$fopr ;open by Rad50 device descriptor ;RT11 only -- used to open the device ;for directory processing. Exit via ;cret$$ or $$fope if error. ;If successful, the number of blocks in ;the file is stored in the first word of ;the block buffer. Description Actually open the RT11 file, doing data buffer management and post-open cleanup. Bugs  C Compiler and Library Page 5-18 $$fopt Scan options parameter for fopen 5.15 Scan options parameter for fopen ____ _______ _________ ___ _____ ********** * $$fopt * ********** File name: iofopt.mac Usage mov iov,r4 ;r4 -> iov call $$fopt ;C$PMTR+2(r5) => options string ;return: option flags in fdb ;r0 random ;error: return to caller via $$fope Description $$fopt parses the options argument in calls to fopen, freopen(), or fwild(). It returns to the caller (via $$fope) if the argument was incorrect. Bugs  C Compiler and Library Page 5-19 $$fsav Floating-point support routines 5.16 Floating-point support routines ______________ _______ ________ ********** * $$fsav * ********** File name: fis.mac Usage $$fsav /* Floating save */ $$frta /* Return to caller a */ $$frtb /* Return to caller b */ Description These routines are used internally by the floating-point simulation package. They are never called by the C program. Bugs BEWARE: untested. Note also that these routines are single-precision, whereas C requires double precision. When/if floating-point becomes a reality, something better will have to be done.  C Compiler and Library Page 5-20 $$gcmd Parse command line 5.17 Parse command line _____ _______ ____ ********** * $$gcmd * ********** File name: getcmd.mac Usage argc = $$gcmd(text, in, out, avp, task) char *text; /* Command line */ char **in; /* stdin filename */ char **out; /* For stdout filename */ char ***avp; /* Gets argv[] location */ char *task; /* Task name if nonnull */ Description: Parse the command line, building the argv[] table. If I/O redirection is encountered, in and out are modified accordingly. NOTE: $$gcmd will modify text. argv[] entries will point to bytes in text. If not NULL, the task name will become argv[0]. Unquoted arguments will be forced to lowercase, duplicating the action of Vax-11 C. $$gcmd() returns the number of arguments encountered. $$gcmd() is called in the following fashion: /* * Default input is on tty */ char **infile = &def_in; char *def_in = "tt:"; /* * Default output is on tty */ char **outfile = &def_out; char *def_out = "tt:"; /* * Define argv[] pointer and dummy command * line. */ char **argvp; char *dummy = "main"; int argc;  C Compiler and Library Page 5-21 $$gcmd Parse command line ... argc = $$gcmd((strlen(cmdlin) == 0) ? dummy : cmdlin, &infile, &outfile, &argvp, $$task); if (argc < 0) error("Bad command line"); stdin = fopen(infile, "r"); if (**outfile == ">") stdout = fopen(*outfile + 1, "a"); else stdout = fopen(*outfile, "w"); Bugs In order to compensate for a problem with native RT11, the "parity" bit is erased from the argument text. This will need modification to handle the Dec Internation character set.  C Compiler and Library Page 5-22 $$get Get a record 5.18 Get a record ___ _ ______ ********* * $$get * ********* File name: ioget.mac Usage RSX: mov #iov,r4 ;r4 -> i/o vector mov #buffer,r0 ;r0 -> buffer mov buflen,r1 ;r1 := max. buffer size call $$get ;Get a record VF$EOF and/or VF$ERR are set on error or end of file. r0 := actual record length, -1 on error or end of file. Other registers preserved. RT11: mov #blknbr,r0 ;r0 := block to read call $$get ;Get block (.gtline record) VF$EOF and/or VF$ERR are set on error or end of file. r0 is zero if success, -1 on error or end of file. Other registers preserved. clr r0 ;End of file error jmp $$geof ;(called by $$getc) Description $$get is the internal "get a record" routine. Note that the maximum record size (r1) is only needed on RSX. On RT11, it is fixed at 512. bytes for files and 82. bytes for terminal lines. If the file is defined as "stream" (the "n" flag was not set when the file was opened using fopen()), the end of the line will be represented by the newline (\n) character, and NULL's will be removed. Bugs  C Compiler and Library Page 5-23 $$getc Get characters 5.19 Get characters ___ __________ ********** * $$getc * ********** File name: iogetc.mac Usage mov #iov,r4 ;r4 -> i/o vector call $$getc ;Get a character Description $$getc is the internal "get a byte" routine. The next byte in the indicated file is returned in r0. All other registers are preserved. $$getc will allocate a buffer if necessary. This routine removes all NULL bytes and from sequences unless the file was opened with the 'n' (nostream) option. Bugs RT11 uses .gtline to read from the user's terminal (thus tracking indirect command files). To read from the physical terminal, fopen "TT:" using "n" mode. RSTS/RT11 has problems reading using either .ttyin or .gtline. There is thus special case code to force "native" system calls.  C Compiler and Library Page 5-24 $$init One-time initialization code 5.20 One-time initialization code ________ ______________ ____ ********** * $$init * ********** File name: init.mac Usage Internal $$init() Description When a C program is started, a command line is parsed to form the argv[] array and the standard input, output, and error files are opened. main() may be declared as follows: main(argc, argv) int argc; char *argv[]; { register int i; /* Arg counter */ for (i = 1; i < argc; i++) { printf("arg[%d] == %s\n", i, argv[i]); } } Note the following: On RSX11/M (even emulated), argv[0] will be set to the task name. On RT11 modes, argv[0] will be set to a dummy value. If no command line is passed to the program, it will prompt the task name (or "Argv") and read a line from the command terminal. To disable this, the user program may define a global flag as follows: $$narg = 1; main (argc, argv) { ... }  C Compiler and Library Page 5-25 $$init One-time initialization code If $$narg is initialized non-zero and no command line is passed to the program, or if the initialization sequence fails to read an argument, main() will be called with one argument. The command line prompt may be changed from the task name (or "Argv") by defining a global string as follows: char *$$prmt = "Command line prompt" main(argv, argc) { ... On Vax VMS, the program may be installed as a "foreign command" by a command such as: $ command :== $disk:[dir]filename and executed by typing: $ command arg1 arg2 Internal MAINTAINERS, Please Note This module contains code that is sensitive to particular releases of the various operating systems. Also, there is code that is sensitive to the various types of operating system emulators. The maintainer should strive to keep all such code in this module. This module has been tested on VMS V3.0 and V3.1, RSTS/E V7.1, RT11 V4.0, and RSX-11M V4.0. It may not work correctly on earlier (or later) releases. Note especially the "secret patch" to allow Decus C to read stream files on VMS V3.0 (and V3.1), and the command line parser for VMS version 3.0 and later. This code will require examination on every release of VMS. Diagnostics Can't parse command line ?C-Standard input, [filename]: error text ?C-Standard output, [filename]: error text ?C-No memory. The "can't parse" message is given if the command line format is incorrect (because of unbalanced quotation marks, for example).  C Compiler and Library Page 5-26 $$init One-time initialization code The "standard input" or "standard output" messages are a user error if input or output are redirected and the associated files cannot be opened. The text should be self-explanatory. The "no memory" message suggests a severe case of program immensity. On RSX systems, it probably means that the task was not built /CP (checkpointable). All errors are fatal. Bugs On RSTS/RSX, command lines are limited to 80 bytes, although 128 byte commands are feasable. On VMS V3.0 and V3.1, the command name includes the expanded form of the command name. This means that long command name translations coupled with long argument strings may cause the total argument string to exceed 80 bytes. Such arguments will be truncated by the operating system without warning. The work-around is to make use of logical names: $ assign $disk[directory.subdirectory] bin $ program :== $bin:prog The expanded form of the "program" command is just "bin:prog". On VMS V3.0 and V3.1, the distributed RSX file service (FCS) refuses to open "stream Ascii" files. This module contains a dynamically-installed patch to the open routine. An error message will be printed if the patch cannot be installed correctly. The VMS3.0 compile-time switch enables this patch. There is also code in fopen.mac that is affected by this patch. It might be reasonable to make error messages non-fatal so $$init could be called by a user program. On RSX, the program aborts (by executing a BPT instruction) if the program fails to open stderr or obtain partition parameters.  C Compiler and Library Page 5-27 $$link Print memory list 5.21 Print memory list _____ ______ ____ ********** * $$link * ********** File name: malink.mac Usage $$link(); /* Print memory list */ Return: all registers preserved Description Subroutine $$link() writes the allocation list onto stderr. It was written to debug malloc() but may be useful for debugging programs that write randomly in memory. Note that it preserves all registers. Diagnostics Bugs  C Compiler and Library Page 5-28 $$ltoa Convert long to Ascii 5.22 Convert long to Ascii _______ ____ __ _____ ********** * $$ltoa * ********** File name: ltoa.mac Usage $$ltoa(buff, radix, value); char *buff; /* Where it goes */ int radix; /* Conversion radix */ long value; /* What to convert */ Description Called by printf to convert a long integer from binary to Ascii, storing the result in buffer. The radix argument determines the conversion: d Signed decimal o Octal u Unsigned decimal X Hex (10-15 = A-F) x Hex (10-15 = a-f) Bugs  C Compiler and Library Page 5-29 $$main Start of C programs 5.23 Start of C programs _____ __ _ ________ ********** * $$main * ********** File name: suport.mac Usage $$main:: /* Start of C programs */ extern int $$opsy; /* Operating system */ extern int $$rsts; /* Non-zero if RSTS/E */ extern int $$vms; /* Non-zero if VMS */ extern int $$pos; /* Non-zero if P/OS */ extern int $$uic; /* RSX: Default uic */ extern int $$stnd; /* Stack end point */ extern int $$scca; /* RT11: .scca control */ extern char $$task[]; /* RSX: task name */ extern int $$tick; /* Clock interrupt rate */ Internal extern int (*$$pptr)(); /* Profile printer */ extern int $$argc; /* Argument count */ extern int *$$argv[]; /* Argument list ptr. */ extern char *$$mtop; /* Free memory start */ extern char *$$mend; /* Free memory end */ Description This module contains the run-time startoff for C programs. It intializes the C environment and calls the main() subroutine. On return from the main program, exit() is called to close all files and return to the operating system. The following globals are defined in this module: $$opsy Operating system unique value. This value is 7 on RT11, and set as per the GTSK$ directive on RSX-based systems: RSX11-D 0. RSX11-M 1. RSX11-S 2. IAS 3. RSTS/E V7 4. VMS 5.  C Compiler and Library Page 5-30 $$main Start of C programs RSX11-M+ 6. RT11 7. P/OS 9. $$rsts This value is non-zero if the program is running on RSTS/E. It is zero if the program is running native RSX, RT11, P/OS or VMS compatibility mode. $$vms This value is non-zero if the program is running (in compatibility mode) on Vax VMS. It is zero if the program is running native RSX, RT11, P/OS or on RSTS/E. $$pos This value is non-zero if the program is running on the Professional P/OS. It is zero if the program is running native RSX, RT11, or on RSTS/E or VMS. $$stnd The (top) end of the stack on entrance. $$scca On RT11, the .scca control word. This is needed to allow RSTS/E programs to trap end of file. $$task On RSX, the task name in Ascii. $$tick The clock interrupt rate. This is set at initialization on RT11 and on the first call to time() or ftime() on RSX. $$uic On RSX, the default UIC word from GTSK$. Internal All $$ values are for internal communication among runtime library routines. I.e., let them alone. Diagnostics On RSX, the task aborts with a BPT if the standard error file did not open. Otherwise, explanatory error messages are printed. Bugs  C Compiler and Library Page 5-31 $$mchk Verify memory allocation pointers 5.24 Verify memory allocation pointers ______ ______ __________ ________ ********** * $$mchk * ********** File name: mamchk.mac Usage $$mchk(); /* Check memory list */ Description Subroutine $$mchk() checks allocation list pointers. The program is crashed by calling error if something goes wrong. $$mchk preserves all registers. Bugs  C Compiler and Library Page 5-32 $$narg Define default for $$narg 5.25 Define default for $$narg ______ _______ ___ ______ ********** * $$narg * ********** File name: narg.mac Usage int $$narg = ; ... main() { ... } Description If no command line is provided when the program starts, the program will print a prompt on the command terminal, read one line and build the argv[] vector. If this is undesirable, include a global definition of $$narg in your C program as follows: int $$narg = 1; This will supress the command terminal read operation. The argv[] vector will be set to a dummy value. If the user program does not define $$narg, it will be defined so as to enable the prompt. Note that $$narg must be initilized at compilation time. It is tested by the initialization code before the main() program is called. Bugs  C Compiler and Library Page 5-33 $$prmt Null prompt pointer 5.26 Null prompt pointer ____ ______ _______ ********** * $$prmt * ********** File name: prmt.mac Usage char *$$prmt = "Prompt string"; Description This pointer is checked in $$init and if the user has defined $$prmt then it will be used as the task prompt instead of using the task name on RSX or "Argv:" on RT-11.  C Compiler and Library Page 5-34 $$prnt Print formatter 5.27 Print formatter _____ _________ ********** * $$prnt * ********** File name: doprnt.mac Usage $$prnt(format, argvec, iov) char *format; int *argvec[]; FILE *iov; Description $$prnt() performs all formatting operations for printf(), sprintf(), and fprintf(). The formatting options are described int the documentation of printf(). Bugs $$prnt() is functionally identical to the _doprnt() module in Unix and Vax-11 C libraries. Unfortunately, the '_' conflicts with RSX FCS library conventions.  C Compiler and Library Page 5-35 $$put Write a record -- RSX only 5.28 Write a record -- RSX only _____ _ ______ __ ___ ____ ********* * $$put * ********* File name: ioput.mac Usage mov #bufadr,r0 ;r0 -> buffer start mov nbytes,r1 ;r1 := number of bytes mov #iov,r4 ;r4 -> i/o vector call $$put ;Internal put buffer routine Return, r1..r4 preserved. Description $$put is called by RSX-mode routines to write a record. $$put only runs under the RSX library. Using it in RT11-mode will cause the job to abort with a BPT trap. The byte count may be zero for RSX Terminal I/O. If output is to a terminal, stderr will be flushed (first). Bugs  C Compiler and Library Page 5-36 $$putc Output one character to a file 5.29 Output one character to a file ______ ___ _________ __ _ ____ ********** * $$putc * ********** File name: ioputc.mac Usage mov #iov,r4 ; r4 -> I/O vector mov byte,r0 ; r0 := byte to output call $$putc Description $$putc is the internal call to write one character to an indicated file. On return, all registers are preserved, even r0. $$putc will allocate a record buffer if necessary. If an error is detected, $$putc will return to the original (C-language) caller. Bugs  C Compiler and Library Page 5-37 $$qiow Call RSX executive service 5.30 Call RSX executive service ____ ___ _________ _______ ********** * $$qiow * ********** File name: ioqiow.mac Usage mov ,r0 mov IOV pointer,r4 mov onto the stack, right to left call $$qiow bcs Description Issue a qio$ directive for all I/O requests needing such. Uses r0, r1. This routine is used only in the RSX library. Using it in the RT11 library will cause the program to abort with by executing a BPT instruction. Bugs  C Compiler and Library Page 5-38 $$rtim Date and time conversion 5.31 Date and time conversion ____ ___ ____ __________ ********** * $$rtim * ********** File name: rtime.mac Usage $$rtim(buffer); struct TIME { int year; /* G.TIYR year - 1900 */ int month; /* G.TIMO Jan. = 1 */ int day; /* G.TIDA */ int hour; /* G.TIHR 00 .. 23 */ int minute; /* G.TIMI 00 .. 59 */ int second; /* G.TISC 00 .. 59 */ int tick; /* G.TICT 00 .. tsec-1 */ int tsec; /* G.TICP tick/second */ } buffer; Description Stores the current time of day in the buffer. The format is compatible with the RSX11-M GTIM$ executive service. Bugs  C Compiler and Library Page 5-39 $$scan Formatted input conversion 5.32 Formatted input conversion _________ _____ __________ ********** * $$scan * ********** File name: doscan.mac Usage $$scan(fmt, args, iov) char *fmt; /* Format string */ int *arg[]; /* Arg vector */ FILE *iov; /* File descriptor */ Description $$scan() does parsing for scanf(), etc. See the description of scanf() for more details. Bugs $$scan() is functionally identical to the _doscan() routine in Unix and Vax-11 C libraries. Unfortunately, the leading '_' conflicts with RSX FCS library name conventions.  C Compiler and Library Page 5-40 $$svr1 Save registers r1-r5 on the stack 5.33 Save registers r1-r5 on the stack ____ _________ _____ __ ___ _____ ********** * $$svr1 * ********** File name: savr1.mac Usage jsr r5,$$svr1 ;Save r1-r5 on the stack ... return ;Restore r1-r5 and return to caller Description Save general registers r1-r5 on the stack and return to the caller. When the caller executes an return (rts pc), it will cause the original r1-r5 to be restored and the program will return to the original caller. On return, the caller's registers are as follows: R1 02(SP) R2 04(SP) R3 06(SP) R4 10(SP) R5 12(SP) PC 14(SP) Return to original user Bugs Except for the C-bit, condition codes are not preserved.  C Compiler and Library Page 5-41 $$tens Conversion table for dtoa, atof 5.34 Conversion table for dtoa, atof __________ _____ ___ _____ ____ ********** * $$tens * ********** File name: doutab.mac Usage extern double $$tens[]; Description $$tens[i] has 10^i for the range 0..35  C Compiler and Library Page 5-42 $$utim Convert $$rtim buffer to Unix time 5.35 Convert $$rtim buffer to Unix time _______ ______ ______ __ ____ ____ ********** * $$utim * ********** File name: utime.mac Usage long $$utim(buffer); struct TIME { int year; /* G.TIYR year - 1900 */ int month; /* G.TIMO Jan. = 1 */ int day; /* G.TIDA */ int hour; /* G.TIHR 00 .. 23 */ int minute; /* G.TIMI 00 .. 59 */ int second; /* G.TISC 00 .. 59 */ int tick; /* G.TICT 00 .. tsec-1 */ int tsec; /* G.TICP tick/second */ } buffer; Description The user calls $$rtim() to initialize a buffer. Then, $$utim will convert buffer contents to the number of seconds since Jan 1, 1970. Note: $$utim() does not compensate for local timezone or daylight savings time. Bugs This routine works only in the range: 1970 <= year < 2100  C Compiler and Library Page 5-43 abort Abort program with a BPT trap 5.36 Abort program with a BPT trap _____ _______ ____ _ ___ ____ ********* * abort * ********* File name: abort.mac Usage abort() Description After closing all files, the program exits by executing a BPT trap. Bugs  C Compiler and Library Page 5-44 abs Integer absolute value 5.37 Integer absolute value _______ ________ _____ ******* * abs * ******* File name: abs.mac Usage abs(val) int val; Description Return absolute value of the integer argument. Bugs  C Compiler and Library Page 5-45 alloc Allocate memory 5.38 Allocate memory ________ ______ ********* * alloc * ********* File name: alloc.mac Usage char * alloc(n); /* -1 if no space */ Description Allocate the requested number of bytes, returning a pointer to the first. The program image will be expanded as needed. alloc() returns -1 if the requested space could not be allocated. free() is used to return the buffer to free space. See also the description of malloc(), realloc() and sbrk(). Diagnostics Bugs alloc() is obsolete. Use malloc() for new programs.  C Compiler and Library Page 5-46 ascr50 Ascii to Radix-50 conversion 5.39 Ascii to Radix-50 conversion _____ __ ________ __________ ********** * ascr50 * ********** File name: ascr50.mac Usage ascr50(count, input, output) int count; int *output; char *input; Description Convert 'count' characters from ascii to Radix 50. If there aren't a multiple of 3 characters, blanks are padded on the end. The ascii string is moved to the output when finished. The input and output areas may be the same since three input characters are read for every two bytes of output. Bugs  C Compiler and Library Page 5-47 asl$l Shift long << long 5.40 Shift long << long _____ ____ __ ____ ********* * asl$l * ********* File name: asll.mac Usage long asl$l(l, n) long l; long n; long asr$l(l, n) long l; long n; Description Performs shifting of long by long. Only the low-order six bits of the shift argument are examined. This is compatible with the hardware ASH instruction. Note that, if n is negative: (l << n) == (l >> (-n)) Bugs  C Compiler and Library Page 5-48 asl$li Shift long << integer 5.41 Shift long << integer _____ ____ __ _______ ********** * asl$li * ********** File name: aslli.mac Usage long asl$li(l, n) long l; int n; long asr$li(l, n) long l; int n; Description Performs arithmetic shifting for integer shift arguments. Note that only the low-order six bits of the shift argument are examined. This is compatible with the hardware shift instruction. Bugs  C Compiler and Library Page 5-49 asr$u Right shift unsigned >> integer 5.42 Right shift unsigned >> integer _____ _____ ________ __ _______ ********* * asr$u * ********* File name: asru.mac Usage unsigned asr$u(u, n) unsigned u; int n; Description Performs u >> n for unsigneds. Note that, if n is negative, it acts as if (u << (-n)) were executed. Bugs  C Compiler and Library Page 5-50 atod Convert Ascii to double floating 5.43 Convert Ascii to double floating _______ _____ __ ______ ________ ******** * atod * ******** File name: atod.mac Usage double atod(buffer) char *buffer; Description Converts a double-precision floating point number written in scientific notation from ASCII to a "double" number. The BNF for numbers which can decoded by this routine follows: := := | | := | . | . | . := | := { E | e | D | d } := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 := + | - | The conversion stops on the first non-legal character. (Note: if this routine is declared type char *, it will return a pointer to the first non-legal character.) Bugs Internal If the C library is compiled using "inline EIS" (C$$EIS=1), hardware floating point is also required. Note: This routine uses the table in the DOUTAB module.  C Compiler and Library Page 5-51 atof Convert Ascii to double floating 5.44 Convert Ascii to double floating _______ _____ __ ______ ________ ******** * atof * ******** File name: atof.mac Usage double atof(buffer) char *buffer; Description Converts a double-precision floating point number written in scientific notation from ASCII to a "double" number. The BNF for numbers which can decoded by this routine follows: := := | | := | . | . | . := | := { E | e | D | d } := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 := + | - | The conversion stops on the first non-legal character. (Note: if this routine is declared type char *, it will return a pointer to the first non-legal character.) Bugs Internal If the C library is compiled using "inline EIS" (C$$EIS=1), hardware floating point is also required. Note: This routine uses the table in the DOUTAB module.  C Compiler and Library Page 5-52 atofd Convert ASCII to floating -- dummy 5.45 Convert ASCII to floating -- dummy _______ _____ __ ________ __ _____ ********* * atofd * ********* File name: atofd.mac Usage double atof(buffer) char *buffer; Description This is a dummy routine that is always present in the Decus C run-time library. If a program attempts to convert an ASCII string to a floating point value (by calling scanf() with a '%f' format effector), the program will crash. If floating point conversion is needed, the conversion routine must be named in the link or task-build command line as follows: RSX: TKB file=file,c:atof,c:c/lb RT11: LINK file,c:atof,c:suport,c:clib/bot:2000 Bugs  C Compiler and Library Page 5-53 atoi Convert Ascii to integer 5.46 Convert Ascii to integer _______ _____ __ _______ ******** * atoi * ******** File name: atoi.mac Usage atoi(p) char *p; Description Convert string to integer. No data checking is performed. The conversion stops at the first non-integer. Leading spaces, tabs, plus-signs and/or newlines are ignored. The integer may be preceeded by a minus sign. Bugs  C Compiler and Library Page 5-54 atol Convert Ascii to long 5.47 Convert Ascii to long _______ _____ __ ____ ******** * atol * ******** File name: atol.mac Usage long atol(p) char *p; Description Convert string to integer. No data checking is performed. The conversion stops at the first non-integer. Leading spaces, tabs, plus-signs and/or newlines are ignored. The integer may be preceeded by a minus sign. Bugs  C Compiler and Library Page 5-55 brk Change memory allocation 5.48 Change memory allocation ______ ______ __________ ******* * brk * ******* File name: brk.mac Usage char * brk(addr); int *addr; Description brk() sets the run-time library's "top of memory" pointer to addr. This value should have been returned by a previous call to sbrk(). Intervening calls to malloc() or file open routines may cause memory to be corrupted by calling brk(). Diagnostics Returns 0 if the brk() argument is reasonable. Returns -1 if it is greater than the current top of memory. (Use sbrk() to increase memory allocation.) Bugs  C Compiler and Library Page 5-56 call Call (Fortran) subroutine from C 5.49 Call (Fortran) subroutine from C ____ _________ __________ ____ _ ******** * call * ******** File name: call.mac Usage return_value = call(routine, count, &arg1, ... &argN); extern int routine(); /* PDP-11 function name */ int count; /* Number of arguments */ Description C Library user-callable interface between C programs and subroutines which follow the standard PDP11 calling sequence. Note that call() saves and restores registers r2-r5. The arguments are as follows: routine The name of the PDP11 routine to be called. count The number of arguments in the calling sequence. arg1 The first argument. For example: extern int sort(); int data_to_sort[NDATA]; int ndata = NDATA; call(sort, 2, &data_to_sort, &ndata); Note that, if the called function returns some other datatype such as a long, the routine and call() must be correctly declared: long call(); long myfun(); long larg; long result; result = call(myfun, 1, &larg);  C Compiler and Library Page 5-57 call Call (Fortran) subroutine from C If call() is being used to return several different datatypes, type coersion may be effective: int call(); long myfun(); long larg; long result; result = (long)call(myfun, 1, &larg); Bugs: WARNING: watch out for trouble if the PDP-11 routine does any I/O. Floating-point data return has not been implemented.  C Compiler and Library Page 5-58 callc Call (Fortran) subroutine from C 5.50 Call (Fortran) subroutine from C ____ _________ __________ ____ _ ********* * callc * ********* File name: callc.mac Usage integer callc ivalue = callc(routine, arg1, ... argN) Description User-callable interface between Fortran programs and subroutines written in C. The arguments are as follows: routine The name of the C routine to be called. arg1 The (location of the) first argument. For example: call callc(sort, table, nelement) Bugs There will be I/O library conflicts since C files have not been initialized. The following problem will occur if a C subroutine is called from a Fortran main program: The C subroutine refers to the save register routine (CSV$) which refers to the C main program. This pulls in a large amount of I/O dependent code, which may cause conflicts. What is worse is that there will be two main programs. It is therefore recommended that there be a C main program that calls Fortran subroutines that may, in turn, call C subroutines.  C Compiler and Library Page 5-59 callc Call (Fortran) subroutine from C The programmer can also define a dummy program that resolves the globals referenced by CSV$ or modify callc.mac to provide the necessary globals.  C Compiler and Library Page 5-60 caller Return name of profiled caller 5.51 Return name of profiled caller ______ ____ __ ________ ______ ********** * caller * ********** File name: caller.mac Usage char * caller(); Description If the routine which called the current function was compiled using the profile option, caller() returns a pointer to the name of the calling function. If the calling function was not compiled with profiling enabled, a pointer to the null string is returned. Example: foo() { foobar(); } foobar() { extern char *caller(); printf("foobar was called by %s\n", caller()); } Internal Warning -- this routine is sensitive to the format of the environment frame and profile information layout. If csv$, pcsv$, or $$prof change, this may have to be modified. Bugs  C Compiler and Library Page 5-61 calloc Allocate and Initialize Memory 5.52 Allocate and Initialize Memory ________ ___ __________ ______ ********** * calloc * ********** File name: calloc.mac Usage char * calloc(n, m); /* NULL if no space */ int n; /* Number of elements */ int m; /* Size of an element */ Description Calloc() allocates space for n elements, each m bytes long. On return, the space is zero'ed. The program image will be expanded as needed. If the requested space cannot be allocated, calloc() returns NULL. See also the description of malloc(), realloc() and sbrk(). The space is returned by calling free(). Diagnostics Bugs  C Compiler and Library Page 5-62 calltr Trace Path to the Caller 5.53 Trace Path to the Caller _____ ____ __ ___ ______ ********** * calltr * ********** File name: calltr.mac Usage calltrace(outfd); FILE *outfd; Description calltrace() prints the calling path (from main()) to the routine that called calltrace()) on the indicated file. The path is printed on one line as: [ main sub1 sub2 ] If a subroutine within the path was not compiled with profiling, or does not start with a call to the C register register save routine, it will be printed as (where is the octal address of the entry to the routine). Note that the last entry on the line is the routine that invoked calltrace(). A call trace will be printed on exit if profiling is enabled and the program aborts or calls error(). Internal Warning -- this routine is sensitive to the format of the environment frame and profile information layout. If csv$, pcsv$, or $$prof change, this may have to be modified. A special entry for error() is provided, which allows the proper "bug" address to be displayed, rather than the return address of error() itself. Bugs  C Compiler and Library Page 5-63 clearerr Clear file error flags 5.54 Clear file error flags _____ ____ _____ _____ ************ * clearerr * ************ File name: cleare.mac Usage clearerr(iop); FILE *iop; Description Clear the error flags for an open file. This may be needed for interaction with the user's console terminal. Bugs  C Compiler and Library Page 5-64 concat Concatenate strings 5.55 Concatenate strings ___________ _______ ********** * concat * ********** File name: concat.mac Usage char * concat(out, in0, in1, ..., inN, 0); char *out; char *in0, in1, ... inN; Description Concat concatenates the argument strings. It returns a pointer to the first byte of out. Bugs  C Compiler and Library Page 5-65 copy Copy a given number of bytes 5.56 Copy a given number of bytes ____ _ _____ ______ __ _____ ******** * copy * ******** File name: copy.mac Usage char * copy(out, in, nbytes) char *out; /* Output vector */ char *in; /* Input vector */ unsigned int count; /* Bytes to copy */ Description Copy the indicated number of bytes from the input area to the output area. Return a pointer to the first free byte in the output area. The copying will be faster if out and in are either both even or both odd addresses. Bugs  C Compiler and Library Page 5-66 cpystr String copy 5.57 String copy ______ ____ ********** * cpystr * ********** File name: cpystr.mac Usage char * cpystr(out, in); char *out; char *in; Description Copy "in" to "out". Return a pointer to the end of out. This allows the following usage: char *ptr; char buffer[BUFSIZ]; extern char *cpystr(); ptr = cpystr(buffer, text); ptr = cpystr(ptr, more_text); The above sequence appends more_text to the copy of text already moved into the buffer. Bugs  C Compiler and Library Page 5-67 csv$ C register save and restore 5.58 C register save and restore _ ________ ____ ___ _______ ******** * csv$ * ******** File name: csv.mac Usage jsr r5,csv$ ... jmp cret$ Description C program Run-time Environment Each C subroutine starts with a call to CSV$ and exits by jumping to CRET$. Upon exit, the stack need not be equal to its value on entrance. During the execution of all C subroutines, register R5 points to the current "environment." Within a subroutine, it appears as follows: _______________ | | SP -> | 1st loc. var. | -10(R5) C$AUTO-2(R5) |_______________| | | | Saved R2 | -6(R5) |_______________| | | | Saved R3 | -4(R5) |_______________| | | | Saved R4 | -2(R5) |_______________| | | R5 -> | Saved R5 | |_______________| | | | Return add. | +2(R5) |_______________| | | | First arg. | +4(R5) C$PMTR+0(R5) |_______________| | |  C Compiler and Library Page 5-68 csv$ C register save and restore | Second arg. | +6(R5) C$PMTR+2(R5) |_______________| Within a subroutine, Registers R0-R4 and the top of the stack, (sp) are available for use. Registers R0 and R1 are not preserved by subroutines and may be used to pass a return value. R5 must not be modified by a subroutine. All variable addressing must be done by offsets to R5. Subroutine arguments must be accessed by reference to C$PMTR. Subroutine local variables must be accessed by reference to C$AUTO. This permits modification of calling sequences without rewriting all subroutines. CSV$ refers to global symbol $$main to call the run-time startup program from the (RSX) library. Internal The global symbols needed for the Whitesmith's C compiler are also included. Bugs  C Compiler and Library Page 5-69 ctime Convert time value to ascii 5.59 Convert time value to ascii _______ ____ _____ __ _____ ********* * ctime * ********* File name: ctime.mac Usage #include char * ctime(tvecp) long *tvec; /* Time value pointer */ char * asctime(tm) struct tm *tm; /* Time buffer pointer */ Description ctime() converts a time value, as returned by time() to an ascii string. For compatibility with previous versions, ctime(0) obtains and converts the current time of day. Note, however, that ctime(0) is not portable. asctime() converts a time vector, as returned by localtime() to an ascii string. The string is statically allocated. It has the format Sun Sep 16 01:03:52 1973\n\0 012345678901234567890123 4 5 0 1 2 All the fields have constant width. To remove the trailing newline, just: char *tp; extern char *ctime(); int tvec[2]; time(&tvec); /* Get time */ tp = ctime(&tvec); /* in Ascii */ tp[24] = '\0'; /* Fix newline */ Bugs  C Compiler and Library Page 5-70 ctime Convert time value to ascii There is no range checking on the information passed.  C Compiler and Library Page 5-71 ctype Character classification type table 5.60 Character classification type table _________ ______________ ____ _____ ********* * ctype * ********* File name: ctype.mac Usage #include mov #MASK,r0 jmp $$ctype Description This module contains the bit-mask table and common code for the is... and to... functions. Bugs No provisions are made for national letters. Maintainers note that source for a test program is included.  C Compiler and Library Page 5-72 ddtoa Convert floating to ASCII -- dummy 5.61 Convert floating to ASCII -- dummy _______ ________ __ _____ __ _____ ********* * ddtoa * ********* File name: dtoad.mac Usage $$dtoa(buff, value, field, dplace) char *buff; /* Where it goes */ double value; /* What to convert */ int field; /* Maximum field width */ int dplace; /* Decimal part width */ Description This is a dummy routine that is always present in the Decus C run-time library. If a program attempts to convert a floating point value to ascii (by calling printf() with a '%f' format effector), an error message will be generated. If floating point conversion is needed, the conversion routine must be named in the link or task-build command line as follows: RSX: TKB file=file,c:dtoa,c:c/lb RT11: LINK file,c:dtoa,c:suport,c:clib/bot:2000 Bugs  C Compiler and Library Page 5-73 delete Delete a named file 5.62 Delete a named file ______ _ _____ ____ ********** * delete * ********** File name: delete.mac Usage delete(filename) char *filename; Description Delete the named file. Returns 1 on success, 0 on error (such as file not found). If an error occurs, $$ferr can be checked for the error code. On RSX modes, the filename as passed need not include an explicit version number. If none is provided, file.nam;0 will be deleted. Note that the filename returned by fgetname() always includes an explicit version. On RT modes, the only error ever returned is "File not found". Bugs On RSX/VMS, the file must be in the user's current ("SET DEFAULT") directory. On RSTS, "SY0:" cannot be distinguished from "SY:".  C Compiler and Library Page 5-74 div$li Long division and modulus 5.63 Long division and modulus ____ ________ ___ _______ ********** * div$li * ********** File name: divl.mac Usage div$li(long, integer) div$l(long, long) mod$li(long, integer) mod$l(long, long) Description Division with long result. Called by the compiler when the appropriate code sequences are encountered. Bugs Warning -- an internal version of cret$ is present. Change one, change both.  C Compiler and Library Page 5-75 eis$i EIS emulator module 5.64 EIS emulator module ___ ________ ______ ********* * eis$i * ********* File name: eis.mac Usage asl$i(a, b); /* Execute a << b */ asr$i(a, b); /* Execute a >> b */ mul$i(a, b); /* Execute a * b */ div$i(a, b); /* Execute a / b */ mod$i(a, b); /* Execute a % b */ Description All arguments are integers. These routines are called by the C compiler to perform the indicated operations. The module may be conditionally compiled to generated hardware EIS operations. Edit RT11.MAC or RSX.MAC to define C$$EIS as needed: 0 Emulate EIS operations 1 Generate EIS operations C$$EIS is defaulted zero for RT11, non-zero for RSX. If n is negative, x << n == x >> (-n) and v.v. Note: div$i returns the remainder in r1. This may be useful for assembly-language programs that need both the quotient and remainder. To explicitly position this module in an overlay structure, refer to the title, EIS$I. Bugs Divide by zero yields zero for the quotient and remainder.  C Compiler and Library Page 5-76 envsave Multi-level function return 5.65 Multi-level function return ___________ ________ ______ *********** * envsave * *********** File name: envset.mac Usage int * envsave(); envreset(frame, hval, lval) int *frame; /* Frame pointer */ int hval; /* High-order return */ int lval; /* Low-order return */ Description These functions permit a multi-level return from a C function to one of its dynamic ancestors in the stack. Envsave() returns the address of the frame of its caller. Later calls to envreset() with this pointer as an argument will create the illusion that the last function invoked by the caller of envsave() returned directly with a value equal to the parameter(s) to envreset(). Envreset() simulates a return to the function whose frame pointer matches frame (the result of a previous call to envsave()). Envreset() may be made to look as if it is returning a one or two word value. If only a single integer value is passed in addition to envreset(), it looks as if a 1-word value was returned. If two integers (or equivalently, a long) are specified, it looks like a long is returned. Thus any 1 or 2 word value may be returned because of the lax type checking in C. It is catastrophic to attempt to return to a function which has itself already returned!!! The following illustrates use of envsave() and envreset(): int *save_frame;  C Compiler and Library Page 5-77 envsave Multi-level function return process() { ... save_frame = envsave(); if (subroutine()) { /* * Success */ } else { /* * Failure */ } } subroutine() { /* * Abort on error */ if (...) envreset(save_frame, 0) /* * Success */ return(1); } When subroutine() detects an error, it calls envreset() to return to the caller of process(), passing a "failure" flag. Bugs If the caller of envsave() has already returned, disaster will result. It is highly recommended that programs use setjmp/longjmp instead.  C Compiler and Library Page 5-78 error Error exit from C programs 5.66 Error exit from C programs _____ ____ ____ _ ________ ********* * error * ********* File name: error.mac Usage error(format, arglist); /* Fatal error exit */ Description An error message is written to stderr and the program exits. If profiling was enabled, a subroutine call trace will be written to stderr. The exit status, $$exst, will be set to "error". Diagnostics Bugs  C Compiler and Library Page 5-79 exit Exit from C programs 5.67 Exit from C programs ____ ____ _ ________ ******** * exit * ******** File name: exit.mac Usage exit(status); /* Exit, no return */ exits(status); /* Exit with status */ $$fail(); /* Immediate exit */ extern int $$exst; /* Exit status value */ Internal jmp $$exit ;Call exit routine Description On exit, the following sequence occurs: 1. The user-supplied wrapup() function is called. 2. User-supplied finalizers are called. 3. Profiles (if requested) are printed. 4. All files are closed. 5. The program exits to the operating system. By calling exits() with an appropriate value, the program can pass an exit status code to the operating system monitor. The RT11 and RSX11 monitors define exit status codes differently; the value passed to exits() is not checked for consistancy. RT11 RSX Meaning 1. 1. IO_SUCCESS -- no message is printed 2. 0. IO_WARNING -- minor error 4. 2. IO_ERROR -- serious error 8. 4. IO_FATAL -- severe error Calling exit() with some other value is equivalent to calling exits(IO_SUCCESS). This is compatible with Unix programs that exit by calling exit() without parameters. Note that the program may also set a value into $$exst and exit via exit():  C Compiler and Library Page 5-80 exit Exit from C programs extern int $$exst; ... $$exst = IO_WARNING; exit(); If the program calls, or jumps to, $$fail, it will immediately exit to the operating system without closing files, calling wrapup() or finalizers, or writing a profile file. Diagnostics Bugs  C Compiler and Library Page 5-81 fabs Floating absolute value 5.68 Floating absolute value ________ ________ _____ ******** * fabs * ******** File name: fabs.mac Usage double fabs(val) double val; Description Return absolute value of a floating argument. Bugs  C Compiler and Library Page 5-82 fclear Clear file error flags 5.69 Clear file error flags _____ ____ _____ _____ ********** * fclear * ********** File name: fclear.mac Usage fclear(iop); FILE *iop; Description Clear the error flags for an open file. This may be needed for interaction with the user's console terminal. Bugs  C Compiler and Library Page 5-83 fclose Close a currently-open file 5.70 Close a currently-open file _____ _ ______________ ____ ********** * fclose * ********** File name: fclose.mac Usage fclose(iop); FILE *iop; Internal mov #iov,r4 ;r4 -> i/o vector mov ,r0 ;r0 == 0 to free i/o vector call $$clos ;close file. mov #iov,r4 ;r4 -> i/o vector mov ,r0 ;r0 == 0 to free i/o vector call $$fcls ;Free buffer space Description Close the file. Returns 0 if ok, -1 if an error. The error code is saved in $$ferr. Note that stderr is never closed. On RT11-mode, the last block of a disk file which was open for output is filled with nulls. Internal $$clos is called internally to close a file. $$fcls is called internally to free buffer space. After the file has been closed, record buffers (RSX-mode) and the file-name buffer (RT11-mode) will be freed. If r0 is zero on entry, the iov and any wild-card buffer will also be freed. This flag is set non-zero by freopen() or fnext() to close a file without freeing the iov. Bugs  C Compiler and Library Page 5-84 feof Test for end of file 5.71 Test for end of file ____ ___ ___ __ ____ ******** * feof * ******** File name: feof.mac Usage feof(iop); FILE *iop; Description Return 1 if end of file on iop, else zero. Bugs  C Compiler and Library Page 5-85 ferr Test for file error 5.72 Test for file error ____ ___ ____ _____ ******** * ferr * ******** File name: ferr.mac Usage ferr(iop); FILE *iop; Description Return 1 if an error has been seen on the indicated file. Bugs Obsolete, use ferror() instead.  C Compiler and Library Page 5-86 ferror Test for file error 5.73 Test for file error ____ ___ ____ _____ ********** * ferror * ********** File name: ferror.mac Usage ferror(iop); FILE *iop; Description Return 1 if an error has been seen on the indicated file. Bugs  C Compiler and Library Page 5-87 fflush Flush output buffers 5.74 Flush output buffers _____ ______ _______ ********** * fflush * ********** File name: fflush.mac Usage fflush(iop); FILE *iop; Description Flush output buffers. This routine actually does I/O. $$ferr is set if anything unexpected happens. Bugs  C Compiler and Library Page 5-88 fget Input a binary record 5.75 Input a binary record _____ _ ______ ______ ******** * fget * ******** File name: fget.mac Usage fget(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; Description Read a record from the indicated file. Maxbytes is the maximum record size. On RSX, the record is read by a direct call to the file service GET$ routine. Your program must not mix calls to fget() with calls to other I/O routines, such as fgets(). On RT11, the file must have been written by fput(). The actual number of bytes read is returned. Use feof() to test for end of file. Fget() is not present on Unix standard I/O libraries. Internal On RT11, when the record is written by fput(), it is preceeded by a two-byte byte count. This value is one greater than the number of bytes in the record. (If a zero count is read, it will mean "end of file.") Bugs  C Compiler and Library Page 5-89 fgetname Convert file name to Ascii 5.76 Convert file name to Ascii _______ ____ ____ __ _____ ************ * fgetname * ************ File name: fgetna.mac Usage char * fgetname(iop, buffer); FILE *iop; char *buffer; Description Convert the file name to Ascii and put it in the buffer. On native RSX (and RSTS/E emulation) the device name, file name, file type, and version are converted to Ascii. The UIC is converted if it was specified and differs from the job's default UIC. (Note that on VMS compatibility mode, the UIC is unavailable.) The version is converted to octal on native RSX and to decimal on VMS emulation. The result should be sufficient to delete the file. On RT11 modes, the file name passed to fopen() is copied to the buffer without further processing. If the file was opened by an fwild()/fnext() sequence, the correct file name is returned. (On RSTS/E, the PPN is returned as well.) Fgetname() returns a pointer to the buffer argument. Fgetname() is present in the Vax-11 C support library, but is not generally present on Unix implementations. Note that fgetname() returns a fully-qualified file specification including, where possible, the disk, directory, and version of the file. If only the actual file name is needed, the following code segment may be executed. As shown, it writes the file name and filetype (extension) to a global "buffer". getfilename(fd, buffer) FILE *fd; register char *buffer;  C Compiler and Library Page 5-90 fgetname Convert file name to Ascii { register char *tp; register char c; fgetname(fd, buffer); /* * Skip over node and device name */ while ((tp = strchr(buffer, ':')) != NULL) strcpy(buffer, tp + 1); /* * Skip over [UIC] or [PPN] if present */ c = EOS; switch (*tp) { case '[': c = ']'; break; case '(': c = ')'; break; case '<': c = '>'; break; } if (c != EOS && (tp = strchr(buffer, c)) != NULL) { strcpy(buffer, tp + 1); /* * Don't include version */ if ((tp = strchr(buffer, ';')) != NULL) *tp = EOS; } Bugs Various operating systems behave differently.  C Compiler and Library Page 5-91 fgets Read a string from a file 5.77 Read a string from a file ____ _ ______ ____ _ ____ ********* * fgets * ********* File name: fgets.mac Usage char * fgets(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; char * fgetss(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; Description Fgets() reads a string into the buffer from the indicated file. Maxbytes is the maximum number of bytes to read. The string is terminated by a newline character, which is followed by a null. Fgets() normally returns buffer. It returns NULL on end of file or error. If the line being read is maxbytes long or longer, no newline is appended. Fgetss() is identical to fgets() except that the terminating newline is replaced by a null. (This is compatible with gets(), but fgetss() is not present in the Unix standard library.) Note that fgets keeps the newline, while fgetss() and gets() delete it. To delete the newline after executing fgets(), execute the following: buffer[strlen(buffer) - 1] = 0; Bugs Note that fgets() returns the next logical text line. Certain RSX-11 or RMS file formats, such as Runoff output files or task-builder load maps, often have multiple text lines packed into one logical record.  C Compiler and Library Page 5-92 fgets Read a string from a file Fgets() processes these correctly. Note, however, that the record location, as returned by ftell(), is the location of the physical record, as returned by the operating system. The "obvious" ftell/fgets sequence, rfa = ftell(fd); fgets(text, sizeof text, fd); will not work properly if multiple text lines are packed into one RSX-11 record. These routines do not understand some of the more baroque RSX-11 file formats, such as "Fortran carriage control" or VMS print-file format. The typeout program in the tools package, T.C, shows an example of complete record deblocking and "seek to byte" procedure.  C Compiler and Library Page 5-93 fileno Get logical unit number 5.78 Get logical unit number ___ _______ ____ ______ ********** * fileno * ********** File name: fileno.mac Usage fileno(iop) FILE *iop; Description Return the logical unit number associated with the file. (On RT11, the channel number is returned.) Bugs  C Compiler and Library Page 5-94 fill Fill a Block of Memory With a Character 5.79 Fill a Block of Memory With a Character ____ _ _____ __ ______ ____ _ _________ ******** * fill * ******** File name: fill.mac Usage fill(addr, ch, count); char *addr; char ch; unsigned int count; Description: Fill the count characters of memory beginning at addr with the character ch. Note: To fill with zero bytes, you can use zero(), which is slightly faster. Bugs  C Compiler and Library Page 5-95 flun Get logical unit number 5.80 Get logical unit number ___ _______ ____ ______ ******** * flun * ******** File name: flun.mac Usage flun(iop) FILE *iop; Description Return the logical unit number associated with the file. (On RT11, the channel number is returned.) Bugs Obsolete -- use fileno() for transportability.  C Compiler and Library Page 5-96 fmkdl Mark file for deletion -- obsolete 5.81 Mark file for deletion -- obsolete ____ ____ ___ ________ __ ________ ********* * fmkdl * ********* File name: fmkdl.mac Usage fmkdl(iop); FILE *iop; Description fmkdl() closes and deletes the specified file. Returns 0 on success, -1 on error. This routine is obsolete. New programs should call delete() instead. To delete an existing file, the program may execute: char buffer[80]; ... fgetname(iop, buffer); fclose(iop); delete(buffer); Bugs On RT11, the job is aborted with an error message if the file wouldn't parse. $$ferr is set to "file not found" if the program tries to delete something (like the line-printer) that it shouldn't. Note that RT11 does not flush the last buffer before deleting the file. On VMS compatibility mode, the file must be in the user's default directory.  C Compiler and Library Page 5-97 fopen C library file opener 5.82 C library file opener _ _______ ____ ______ ********* * fopen * ********* File name: fopen.mac Usage FILE * fopen(name, mode); char *name; /* File to open */ char *mode; /* Open modes */ FILE * freopen(name, mode, iop); char *name; /* File to open */ char *mode; /* Open modes */ FILE *iop; /* I/O pointer */ Internal mov iov,r4 ;r4 -> iov jmp $$fopn ;Open the file and return to the ;caller via $$fopx or $$fope if error. ;On RSX, fixup append mode if the file ;wasn't found. mov iov,r4 ;r4 -> iov call $$fopo ;Normal open, then exit via $$fopx ;On RSX, $$fopo returns if any error ;occurred. On return, r0 := RSX error code. mov iov,r4 ;r4 -> iov, file is open jmp $$fopx ;Normal exit from fopen ;On RSX, $$fopx allocates the record ;buffer. mov iov,r4 ;r4 -> iov (or r4 == 0) mov code,r0 ;r0 := error code (to go to $$ferr) jmp $$fope ;Error exit from fopen ;$$fope deallocates buffers Description Fopen opens a new or existing file in the indicated mode:  C Compiler and Library Page 5-98 fopen C library file opener r Read the existing file sequentially w Create and write the file sequentially a Append to the file n Not record oriented u RSX-mode "unbuffered i/o" RT11-mode: use .ttyin and .ttyout Either "r", "w", or "a" must be given. "n" and "u" are optional. "n" should be given for "binary" files. Note that "n" mode will create fixed-block records on RSX systems. Append mode does not work on native RT11. Note that "n" and "u" are not compatible with other Unix systems. Implementation Details On RSX, "u" mode files will be created with the "variable-length" attribute. On RSTS/RSX emulation, text files (neither "n" nor "u" specified) will be created with "stream" attribute. On RSX, if the record type bits in the record attribute byte (F.RATT in the FDB) is zero, the file will be read as if the "n" was specified. Note that, if the file contains carriage-return line-feed sequences, the entire sequence will be passed to the user's program. If record attributes are understandable, the carriage-return will be deleted from sequences. On RSX, if the "file" is being opened for write to the same device/unit as stderr (the user's "command console), the character stream is diverted to stderr. This avoids synchronization problems by funnelling all output through the same buffer. In addition, output to any terminal device is done via QIO's to the terminal, IO.WLB for normal mode, IO.WAL for "n" mode. On RT11, when opening a file for writing, a specific block allocation may be included in the Ascii file specification following standard RT-11 syntax: "DKn:file.nam[nnn]" where the "nnn" specifies the number of blocks to allocate to the file. After opening a file successfully, the actual file size (or number of blocks allocated) will be found in (FILE *)fd->io_size. If the RT11 library decides that the file is really the user's command terminal, single-character I/O will be performed (by calling .ttyin and .ttyout). Note that the "special-mode" bits must be set in the Job Status Word by the program if it requires true single-character or immediate return input. Output to the terminal will be performed without buffering, which is useful for  C Compiler and Library Page 5-99 fopen C library file opener screen updating, but otherwise expensive. Fopen() returns NULL on errors -- $$ferr gets an error code. On RT11, this will be a RSTS/E compatible code (described in iov), while on RSX, this will be the FCS error code. On RT11, the file name pointed to by the "io_name" field of the iov is either the file name string as passed to fopen() or an ascii string reconstructed from the 4-word Rad50 device block if the file was opened as part of a fwild/fnext sequence. By saving the ascii string, RSTS/E is able to re-parse logical device names and PPN's, which are not present on native RT11. On VMS compatibility mode, the device and directory of the file name argument are saved in the iov "io_dname" field for use by fgetname(). Note that "no buffer space available" (IE.NBF or E$$NSP) and "invalid lun" (IE.ILU or E$$NOC) may be generated by fopen. On RT11, if the file cannot be opened because the user's program has already opened the channel, an E$$ILU error will be returned. The same file may not be used for both reading and writing except if the program writes a disk file, then repositions and reads it using ftell()/fseek(). In this case, the program should call rewind() or freopen() to reinitialize the file before using fseek(). Except in the one specific case of the RT11 console terminal open in "u" mode, an open file must not be used for reading and writing at the same time. Freopen() substitutes the named file in place of the open file -- indicated by iop. The file currently open on iop is closed. Freopen returns iop. If the open failed, iop will be deallocated. Note that freopen loses any pending fwild/fnext status. Internal The following routines/globals are for use by fopen/fwild. If any of these routines detect an error, they return to the fopen() caller with an appropriate error code in $$ferr. $$fope Error exit from fopen $$fopn Normal open, hack append $$fopx Normal exit from fopen Warning: fopen() in RSX/RSTS mode uses unpublished  C Compiler and Library Page 5-100 fopen C library file opener information to obtain the PPN [UIC] of an open file. This code (in iocsi.mac) may require modification for subsequent releases of RSTS/E. Bugs Append mode cannot work on native RT11 given the design of the RT11 file system. The RT11 file system does not support files greater than 65535 blocks long. RT11 does not get the actual keyboard name of the console terminal, although this isn't too hard to do on RT11/RSTS/E. Freopen() cannot be used to assign a file to stderr as there is code throughout the i/o package for special treatment of stderr. For example, it cannot be closed by a user-written program. In RSX modes, the maximum number of files that may be simultaneously open is defined at assembly time by a macro (FSRSZ$) which is expanded when fopen.mac is assembled. The default FSRSZ$ parameter is 4. This may be modified by using the task builder /ACTFIL=n option. The default FSRSZ$ value may be specified when the RSX library is built by editing assembly parameter N$$FIL in RSX.MAC. Internal This module contains release-specific code for VMS V3.0 to enable Decus C programs to read "Ascii stream" files.  C Compiler and Library Page 5-101 fprintf Formatted Output Conversion 5.83 Formatted Output Conversion _________ ______ __________ *********** * fprintf * *********** File name: fprint.mac Usage fprintf(iov, format, arg1, ...); FILE *iov; char *buffer; char *format; Description fprintf() converts and formats its arguments, writing the result to the indicated file. For information on formatting, please refer to the description of printf. Bugs  C Compiler and Library Page 5-102 fps Set floating point status (FPS) 5.84 Set floating point status (FPS) ___ ________ _____ ______ _____ ******* * fps * ******* File name: fps.mac Usage #include fps(status) unsigned int status; Description This routien sets the floating point status by simply executing the LDFPS instruction. This allows a user program to switch between roundoff and truncation modes or enable/disable floating point interrupts. Bit definitions are in the include file, "fps.h". For example, to enable rounding and all fpu error interrupts except underflow, do the following: #include fps(FIUV | FIV | FIC); Bugs The C library doesn't initialize the floating point status. This routine -- with appropriate parameters -- should be in all C main programs that require floating point operations.  C Compiler and Library Page 5-103 fput Output a binary record 5.85 Output a binary record ______ _ ______ ______ ******** * fput * ******** File name: fput.mac Usage fput(buffer, nbytes, iop); char *buffer; int nbytes; FILE *iop; Description The specified record is written to the file. The file must have been opened 'n' so newlines aren't stuffed here and there. On RT11, the file is only readable by fget. Nbytes is always returned. A call to ferr() after calling fput() is advised. Bugs On RT11, file close zeros the current output block. To prevent fget() from reading "zero length" records, fput writes "record count + 1" on the file.  C Compiler and Library Page 5-104 fread Input a record 5.86 Input a record _____ _ ______ ********* * fread * ********* File name: fread.mac Usage int fread(object, sizeof (*object), nitem, iop) int nitem; FILE *iop; Description Object points to a buffer that is to receive a specified number of items from the file. fread() returns the actual number of items read. This will be zero if an end-of-file or error was encountered. Bugs  C Compiler and Library Page 5-105 frec Return True if record-oriented file 5.87 Return True if record-oriented file ______ ____ __ _______________ ____ ******** * frec * ******** File name: frec.mac Usage frec(iop); FILE *iop; Description Return 1 if the file is record-oriented. Note: in this context, record-oriented files are not file-structured disks, nor are they the user's console terminal. Other terminals, along with devices such as line-printers, qualify, however. Bugs  C Compiler and Library Page 5-106 fscanf Formatted input conversion 5.88 Formatted input conversion _________ _____ __________ ********** * fscanf * ********** File name: fscanf.mac Usage fscanf(fd, fmt, pointer(s)) FILE *fd; /* Input file pointer */ char *fmt; /* Format string */ Description Fscanf() parses the input file according to the indicated format descriptor, storing the results in the pointer arguments. It returns the number of successfully assigned input items. See the description of scanf() for further documentation. Diagnostics Fscanf() returns -1 if an end of file condition exists and no data was stored. It returns -2 if a palpably incorrect format, such as "%" is encountered. Bugs  C Compiler and Library Page 5-107 fseek Reposition file pointer (seek) 5.89 Reposition file pointer (seek) __________ ____ _______ ______ ********* * fseek * ********* File name: fseek.mac Usage fseek(iop, offset, param); FILE *iop; /* What device to seek */ long offset; /* New read position */ int param; /* Zero for abs. seek */ Description fseek() moves the file pointer to the indicated position. The position must have been returned by ftell() or equal zero for rewind. Param must be zero. The file/device must be seekable. fseek() returns zero if correct, EOF if an error occurs. If no error occurred, error and eof flags are reset. flseek() is an alternate entry with identical parameters and actions. Note that on RSX, fseek() can be used to open a file for update by a sequence such as: fd = fopen("file.nam", "a"); fseek(fd, 0L, 0); /* Rewind file */ If the file was opened on RSX using the 'n' mode switch, it will be opened using file attributes "fixed 512-byte records with no carriage control". The offset pointer is thus a virtual byte number and fseek may be used to freely reposition the file pointer. Bugs  C Compiler and Library Page 5-108 fspool Spool file to default print queue 5.90 Spool file to default print queue _____ ____ __ _______ _____ _____ ********** * fspool * ********** File name: fspool.mac Usage fspool(fp); FILE *fp; /* Open file IOV */ Description This routine is called in lieu of fclose() when it is desired to spool the file to the system line printer. There is no control over the disposition or printout parameters. Fspool() returns zero if the file was spooled, it returns an error code if spooling could not be initiated. If called on native RT11, the file will be closed and an "illegal device error" (E$$NOD = 6) will be returned. If the program needs access to the power of the queue manager print spooler on native RSX, the RSX extensions library spwn() routine should be used to spawn a command line to MCR after closing the file as usual. If the program needs access to the power of the queue manager on RSTS/E, it should close the file and use the routines in the RSTS/E extensions library to execute the UU.SPL system function call. On RSTS/E V7.0, the file is spooled to any line printer (RSX mode) or to LP0: in RT11 mode. The particular line printer cannot be selected without modifying the source of fspool(). If the file was opened by calling fwild()/fnext(), internal buffers will not be freed, allowing the program to call fnext() for subsequent files. Bugs On RSTS/E RT11 mode, error codes will follow the description of the spooling system function call.  C Compiler and Library Page 5-109 ftell Get file position for subsequent seek 5.91 Get file position for subsequent seek ___ ____ ________ ___ __________ ____ ********* * ftell * ********* File name: ftell.mac Usage long ftell(iop); FILE *iop; /* What device to seek */ Description ftell() returns the position of the read/write pointer of the indicated file. This value may be fed back to the file system by calling fseek(). Note that the value is a pointer to the record, not a block or byte pointer. On RSX, the program should flush the current record before calling ftell(). (Flush() is a noop on RT11.) If reading lines of text, the correct sequence is: position = ftell(fd); if (fgets(buffer, sizeof buffer, fd) != EOF) { /* * 'position' locates the record * read by the call to fgets() */ } Make sure you declare ftell() extern long ftell(); If you do not, it will return garbage. Bugs On both systems, the value returned is the position of the file pointer (RFA), as a byte offset from the start of the file. Note, however, that on RSX systems the pointer is to the start of the current record. It is not necessarily the case that the start of a text line equates to the start of a record. RSX supports many file record formats, including Fortran, print_file and "unformatted" (with embedded control information). The  C Compiler and Library Page 5-110 ftell Get file position for subsequent seek latter files may have multiple text lines embedded in each record. This is handled internally by the formatted read routines (i.e., fgets() and getc()). On RSX, the only way to be certain of the exact record/line correspondance is to use the fget() and fput() functions. The T utility program (in the tools library) shows another method of handling this problem. On RSTS/E RT11 mode, ftell will not process "large" files (with more than 65535 blocks) correctly.  C Compiler and Library Page 5-111 ftime Compute time of day (augmented) 5.92 Compute time of day (augmented) _______ ____ __ ___ ___________ ********* * ftime * ********* File name: ftime.mac Usage #ifdef unix #include #include #else #include #endif long ftime(buf); struct timeb *buf; Description ftime returns the time of day in seconds. The time buffer receives the time of day, milliseconds since the current second, and timezone and Daylight Savings time indicators. The time buffer has the following format: struct timeb { long time; /* Time of day */ unsigned millitm; /* Milliseconds */ short timezone; /* Current timezone */ short dstflag; /* Daylight Savings */ }; The time value is the time since midnite, Jan 1, 1970, measured in seconds. The timezone value is the number of minutes that local time differs from GMT. Note that, on Unix, the time buffer definition is stored in the sys directory, while for Decus-C and Vax-11 C, it is stored in the default system library (C: or sys$library: respectively). Bugs  C Compiler and Library Page 5-112 ftime Compute time of day (augmented) The Unix time function returns GMT. Decus C returns local time. Timezone and dstflag are set to zero.  C Compiler and Library Page 5-113 ftty Test if terminal file 5.93 Test if terminal file ____ __ ________ ____ ******** * ftty * ******** File name: ftty.mac Usage ftty(iop) FILE *iop; Description Return 1 if the file is a terminal-type device. In general, this means the user's command terminal. Bugs Obsolete -- use isatty(fileno(iop)) instead for transportability.  C Compiler and Library Page 5-114 fwild Wild-card file open 5.94 Wild-card file open _________ ____ ____ ********* * fwild * ********* File name: fwild.mac Usage FILE * fwild(name, mode); char *name; /* File to open */ char *mode; /* Open modes */ FILE * fnext(iop); FILE *iop; /* I/O pointer */ Description Fwild() opens a new or existing file (whose file name may contain "wild-cards"). Open modes are identical to those given in fopen(). On return, the file name has been parsed, but no file has yet been opened. A NULL return means that the file name did not parse correctly. Fnext() opens the first or next file which was defined by a previous call to fwild(). If fnext() returns NULL, there are no (more) files that match the wild-card specification. fwild/fnext handle RSX file version numbers correctly on VMS compatibility mode (which uses the ODS2 disk structure). Fwild/fnext do not handle version numbers correctly on native RSX systems which use the FILES-11 (ODS1) disk structure. For example, a program can request "foo.*;3", "foo.*;*", "foo.*;0", and "foo.*;-1". Omitting a version number "foo.*" is equivalent to "foo.*;0". Note that version number 0 means the "newest" file, while version number -1 means the oldest. (Version numbers are not used on RT11 or RSTS/E.) For native RSX systems (using the FILES-11 disk structure), an explicit version number and the wildcard version number work correctly. Version numbers 0 and -1 work only if the directory has been reorganized by using the SRD utility program. If the directory has not been reorganized (such that the youngest version appears  C Compiler and Library Page 5-115 fwild Wild-card file open first in the directory), fnext() will yield unpredictable results. On RT-11, the wildcard filename match is handled internally to fwild/fnext. The parser will handle several forms of wild file specs, including imbedded '*' and the single character wildcard '%', and acts the same as the DIRECTORY wildcard handler. For convenience, a '?' acts the same as a '%' in a match string. Note: if a program executes fclose(), all file name information will be lost. The following sequence illustrates proper use of fwild()/fnext(): if (gets(name_buff) == NULL) exit(); if ((fd = fwild(name_buff, "r")) == NULL) error("Can't open %s\n", name_buff); for (count = 0; fnext(fd) != NULL; count++) { /* * Process each file */ while (fgets(buffer, sizeof buffer, fd) != NULL) { /* * Process each record */ } } /* * fnext() fails; the channel is closed. * count has the number of files processed. */ if (count == 0) error("No matching files found"); The following summarizes the types of wild-card processing available on the various implementations of the C support library: Environment Supports Native RSX "*" matches any filename, filetype, or version number. Version ;0 and ;-1 are supported on ODS2 systems. UIC's may not contain wildcards. RSX/VMS As above, note that version ;-1 means the "earliest" version. Note warning below. Directory identifiers may not be wildcarded. VMS systems support ODS2. RSX/RSTS Uses RSTS/E wildcard conventions: "*" replaces filename or filetype. "?"  C Compiler and Library Page 5-116 fwild Wild-card file open matches any character. PPN's may not be wildcarded. Version numbers are not supported on RSTS/E. Native RT11 "*" replaces any string, "%" or "?" match any non-blank character. RT11/RSTS Uses RSTS/E wildcard conventions noted above. Bugs On native RSX systems using ODS1 (FILES-11) disk structures, version numbers will be processed properly only if directories have been sorted (by using the SRD utility program, for example). If directories are not sorted, and fwild() is invoked with version number ;0 or ;-1, it will yield unpredictable results. The command language scan (CSI1$) on VMS compatibility mode does not parse version number -1 (because it has a different meaning on native VMS) and fwild() will consequently fail. If you want the oldest version, fwild() should be invoked with a file name of the type "foo.*" or "foo.*;0" and, before calling fnext() for the first time, you should set the correct bits in the IOV flag word as follows: if ((fd = fwild(file, "r")) == NULL) error("can't open file %s", file); if ((fd->io_flag & IO_VER) != 0 && version_minus_1_wanted) fd->io_flag |= IO_VM1; Flag bit IO_VER signals "version 0 or -1", while bit IO_VM1 signals version minus 1. Again, note that this must be done before the first call to fnext(). On native RT11 and all RSTS/E modes, fwild/fnext will fail if the device is not directory structured (even if no wildcard file is specified). If this is a problem, you should write: if ((fd = fwild(filename, mode)) != NULL) iswild = 1; else if ((fd = fopen(filename, mode) != NULL) iswild = 0; else error("cannot open the file"); The program must then test iswild to determine if it must call fnext() or if processing should be initiated directly.  C Compiler and Library Page 5-117 fwild Wild-card file open On all RSTS/E modes, there may be problems with logical name translation as file name strings must be parsed more than once. Thus, if a programer defines a logical name which is identical to a valid physical device name, a wildcard lookup may access the wrong unit. This problem is described in the RSTS/E documentation. Fwild/fnext was designed to work only with disk devices. It will not necessarily work correctly with other directory-structured devices, such as magtape. Internal If you are always running on RSTS/E, or always running on RSX-11 (native or VMS compatibility mode) or always running on native RT11, you should consider editing fwild.mac to remove unnecessary code. This routine depends on some internal knowledge about RSTS/E and about the implementation of RSX-11 file control services on RSTS/E. It may need modification for subsequent releases of RSTS/E. The implementors do not apologize for the size of this module. The distribution of the C language system includes source code for the SRD (sort directories) utility program.  C Compiler and Library Page 5-118 fwrite Output a record 5.95 Output a record ______ _ ______ ********** * fwrite * ********** File name: fwrite.mac Usage int fwrite(object, sizeof (*object), nitem, iop) int nitem; FILE *iop; Description Object points to a buffer that is contains a specified number of items to be written to the file. fwrite() returns the actual number of items written. This will be zero if an error was encountered. Bugs  C Compiler and Library Page 5-119 getchar Get characters 5.96 Get characters ___ __________ *********** * getchar * *********** File name: getcha.mac Usage getchar(); getc(iop); FILE *iop; Description Getchar() reads one character from the standard input file. getc() reads one character from the indicated input file. Both return EOF on error or end of file. To continue reading from a terminal after EOF, the program may execute: clearerr(iop); Bugs  C Compiler and Library Page 5-120 gets Read a string from stdin 5.97 Read a string from stdin ____ _ ______ ____ _____ ******** * gets * ******** File name: gets.mac Usage char * gets(buffer); char *buffer; Description gets() reads a string into the buffer from the standard input (stdin). The string is terminated by a newline character, which is replaced in the buffer by a null. Gets() returns buffer or NULL on end of file or error. Bugs  C Compiler and Library Page 5-121 gettty Get control terminal name 5.98 Get control terminal name ___ _______ ________ ____ ********** * gettty * ********** File name: gettty.mac Usage gettty(buffer); char *buffer; Description Store the device name of the control terminal in the buffer. If this cannot be done, a null string will be returned. Bugs On RSX modes, gettty() uses the GLUN$ executive directive to obtain the device name and unit number of stderr (which always is assigned to the control terminal). On RT11 modes, gettty() calls iovtoa to return the file name on which stderr was opened. This will not necessarily contain a valid unit number.  C Compiler and Library Page 5-122 getw Input a binary integer from a file 5.99 Input a binary integer from a file _____ _ ______ _______ ____ _ ____ ******** * getw * ******** File name: getw.mac Usage getw(iop); FILE *iop; Description getw() reads one (16-bit) word from the indicated file. The program must call feof() or ferr() to test for end of file or error. Bugs  C Compiler and Library Page 5-123 inchr Find Index of Character in a String 5.100 Find Index of Character in a String ____ _____ __ _________ __ _ ______ ********* * inchr * ********* File name: inchr.mac Usage char * inchr(stng, chr) char *stng; /* String to search in */ char chr; /* Byte to search for */ Description If chr is in stng, return its index, i.e. the offset in bytes from the beginning of the string - inchr("abc",'b') == 1. If chr is not in stng, return -1. See also strchr(). Bugs  C Compiler and Library Page 5-124 index Find First Instance of a Character in a String 5.101 Find First Instance of a Character in a String ____ _____ ________ __ _ _________ __ _ ______ ********* * index * ********* File name: index.mac Usage char * index(stng, chr) char *stng; /* String to search in */ char chr; /* Byte to search for */ Description If chr is in stng, return a pointer to it. If not, return NULL. Bugs Obsolete; use strchr() instead.  C Compiler and Library Page 5-125 iov I/O vector definition 5.102 I/O vector definition ___ ______ __________ ******* * iov * ******* File name: iov.mac Usage #include ... to be supplied ... Bits in iov.io_flag: #define _IOREAD 0000001 /* read */ #define _IOWRT 0000002 /* write */ #define _IONBF 0000004 /* Unbuffered, "u" mode */ #define _IOMYBUF 000010 /* I/O lib. owns buffer */ #define _IOEOF 0000020 /* End of file seen */ #define _IOERR 0000040 /* Error seen */ #define _IOSTRG 0000100 /* For sprintf */ #define _IORW 0000200 /* Open for read/write */ #define IO_CMD 0000400 /* User's command tty */ #define IO_APN 0001000 /* Append mode open */ #define IO_NOS 0002000 /* No newlines needed */ #define IO_NEWL 0004000 /* RSX TTY newline hack */ #define IO_FIL 0010000 /* Disk file */ #define IO_TTY 0020000 /* Terminal device */ #define IO_REC 0040000 /* Record device */ #define IO_OPN 0100000 /* Open file */ #define IO_EOR (IO_ERR | IO_EOF) Bits in iov.io_wflag: #define IO_WLD 0000001 /* fwild: wildcard file */ #define IO_VM1 0000002 /* fwild: version ;-1 */ #define IO_VER 0000004 /* fwild: ;0 or ;-1 */ #define IO_WF1 0000010 /* fwild first flag */ #define IO_NLH 0000020 /* Newlines hack bit */ Bits in iov.io_rsflag (RSTS native only) #define IO_ODT2 0100000 /* ODT mode (RSTS only) */ extern int $$ferr; /* Error word */ extern FILE *stdin; /* Standard input file */ extern FILE *stdout; /* Standard output file */ extern FILE *stderr; /* User's command tty */ extern int $$exst; /* Exit status */  C Compiler and Library Page 5-126 iov I/O vector definition Internal extern FILE *$$luns[]; /* IOV pointer table */ extern FILE *$$lune; /* IOV table end */ extern (int)(char *$$lmax); /* RSX $$luns dim. */ extern char **$$ifil; /* -> stdin file name */ extern char **$$ofil; /* -> stdout file name */ extern int $$nlun; /* RSX: Number of luns */ FILE *$$eiov; /* RSX: Stderr iov */ extern int $$iosb[2]; /* RSX: I/O status */ Description Define the I/O vector structure used for communication by all I/O routines in the C library. Note that it is different for RSX and RT11 modes. Note also that certain bits in IO_FLAG are only meaningful for one flavor of I/O. The RSX-mode IOV contains an entire file data block (FDB). Also, 'io_uic' contains the binary UIC of the directory via which the file is being accessed, not the 'owner' UIC. It is this UIC which is given when fgetname() is called. The RT11-mode IOV contains only enough information to read and write files plus a pointer to an Ascii string with the file name argument to fopen(). The file name is needed for fgetname() and to allow deleting files given the IOV pointer. The following files are defined here: stdin The standard input file. stdout The standard output file. stderr The error output file. Note: on RSX systems, stderr is opened on LUN 1. $$ferr (error word) is also defined here. This is set non-zero if an error occurred when performing I/O. On RSX, the standard I/O error code is returned. On RT11, an error code compatible with RSTS/E usage is returned: Global Value Meaning E$$ILF 02. 002 Illegal file name E$$NOR 04. 004 No room for user on device E$$FNF 05. 005 Can't find file or account E$$NOD 06. 006 Not a valid device E$$ILU 07. 007 I/O channel in use E$$NOO 09. 011 I/O channel not open E$$EOF 11. 013 End of file on device E$$FAT 12. 014 Fatal system I/O failure  C Compiler and Library Page 5-127 iov I/O vector definition E$$ERR 13. 015 User data error on device E$$FND 16. 020 File already found (protected) E$$NOC 17. 021 Too many open files on unit. E$$NSP 32. 040 No memory space for buffer E$$FAT (12) is set only if an "impossible" error occurs. While this may indicate a bug in the RT11 library, it is more likely to be a user programming error (like passing garbage to an I/O routine). E$$ILU (7) is set if fopen tries to open a channel that is already in use. The perror() library routine may be used to print an error message defined for the error code. $$exst (exit status) is used to transmit a termination code to the operating system. The value is set by calling exit() or exits(). The following exit status values are defined in stdio.h: Global #define RSX RT11 Meaning E$$XOK IO_SUCCESS 1 1 Normal E$$XWA IO_WARNING 0 2 Warning E$$XER IO_ERROR 2 4 Error E$$XFA IO_FATAL 4 8 Severe Error Internal In RSX, buffering is done by the RSX file-management services (FCS). The block buffer pointer is unused (but reserved for anybody who cares to add random access). Bugs  C Compiler and Library Page 5-128 irand Random number modulus argument 5.103 Random number modulus argument ______ ______ _______ ________ ********* * irand * ********* File name: irand.mac Usage int irand(arg) int arg; Description Generate a pseudorandom number in the range 0 .. (arg-1). If arg is zero, generate a number in the range 0 .. 32767. Note that the algorithm is prone to nonrandom sequences when considering the next pseudorandom number. irand is equivalent to the following sequence: extern long rand; if (arg == 0) arg = 32767; return(((rand() >> 8) & 32767) % arg); Bugs  C Compiler and Library Page 5-129 isalloc Check If a Pointer Points to Allocated Memory 5.104 Check If a Pointer Points to Allocated Memory _____ __ _ _______ ______ __ _________ ______ *********** * isalloc * *********** File name: isallo.mac Usage int isalloc(buff) char *buff; Description isalloc() returns 1 if buff is a pointer to a block of memory allocated by calloc(), malloc(), or realloc() that has not been freed (by free()); -1 if it is a (recently) freed allocated block; and 0 otherwise. isalloc(NULL) == 0. isalloc(p) will remain -1 after a call of free(p) at least until the next call to calloc(), malloc(), etc. Beyond that, its value is not predictable. Pointers for which isalloc() is non-zero are exactly those that may safely be passed to realloc(). The test done by isalloc() is definitive, unlike the tests done by, for example, free() and msize(), which will yield false positives at least 25% of the time. However, isalloc() is slower. Bugs Not portable.  C Compiler and Library Page 5-130 isalnum Return TRUE if alphanumeric argument 5.105 Return TRUE if alphanumeric argument ______ ____ __ ____________ ________ *********** * isalnum * *********** File name: isalnu.mac Usage isalnum(c); int c; Description Return non-zero if c is an alphanumeric character, 0 otherwise. Bugs  C Compiler and Library Page 5-131 isalpha Test for alphabetic argument 5.106 Test for alphabetic argument ____ ___ __________ ________ *********** * isalpha * *********** File name: isalph.mac Usage isalpha(c); int c; Description Return non-zero if c is an alphabetic character, 0 otherwise. Bugs  C Compiler and Library Page 5-132 isascii Test for 7-bit Ascii character 5.107 Test for 7-bit Ascii character ____ ___ _____ _____ _________ *********** * isascii * *********** File name: isasci.mac Usage isascii(c); int c; Description Return non-zero if c is a 7-bit Ascii character, 0 otherwise. Bugs  C Compiler and Library Page 5-133 isatty Test if terminal file 5.108 Test if terminal file ____ __ ________ ____ ********** * isatty * ********** File name: isatty.mac Usage isatty(channel_number) int channel_number; Description Return 1 if the file open on this channel is a terminal-type device. In general, this means the user's command terminal. Note that the argument is a file descriptor, not a FILE * pointer. File descriptors are used on Unix to identify the channel on which the file is open. As Decus C does not support file descriptor I/O processing, the logical unit number assigned to a file by fopen() is used instead. Use isatty() as follows: if (isatty(fileno(fd))) ... Bugs Note that Decus C channel numbers are not related to Unix file descriptors. Specifically, isatty(0) does not necessarily check stdin. Use isatty(fileno(stdin)) instead.  C Compiler and Library Page 5-134 iscntrl Test for control character argument ;02 5.109 Test for control character argument ____ ___ _______ _________ ________ 02 *********** * iscntrl * *********** File name: isctrl.mac Usage iscntrl(c); int c; Description Return non-zero if C is a control character. Bugs  C Compiler and Library Page 5-135 isdigit Return TRUE if digit argument 5.110 Return TRUE if digit argument ______ ____ __ _____ ________ *********** * isdigit * *********** File name: isdigi.mac Usage isdigit(c); int c; Description Return 1 if c is an Ascii digit, 0 otherwise. Bugs  C Compiler and Library Page 5-136 isgraph Test for graphic alphabetic argument 5.111 Test for graphic alphabetic argument ____ ___ _______ __________ ________ *********** * isgraph * *********** File name: isgrap.mac Usage isgraph(c); int c; Description Return non-zero if c is a graphic character, 0 otherwise. Graphics characters include letters, digits, and punctuation. Space, tab, etc. are not graphics. Bugs  C Compiler and Library Page 5-137 islower Test for lower-case alphabetic argument 5.112 Test for lower-case alphabetic argument ____ ___ __________ __________ ________ *********** * islower * *********** File name: islowe.mac Usage islower(c); int c; Description Return non-zero if C is a lower-case alphabetic character, 0 otherwise. Bugs  C Compiler and Library Page 5-138 isprint Return non-zero if printable argument 5.113 Return non-zero if printable argument ______ ________ __ _________ ________ *********** * isprint * *********** File name: isprin.mac Usage isprint(c); int c; Description Return non-zero if c is a printable character, 0 otherwise. Printable characters include letters, digits, punctuation, and the space character. Tab, newline, etc. are not included. Bugs  C Compiler and Library Page 5-139 ispunct Return TRUE if punctuation argument 5.114 Return TRUE if punctuation argument ______ ____ __ ___________ ________ *********** * ispunct * *********** File name: ispunc.mac Usage ispunct(c); int c; Description Return non-zero if c is an Ascii punctuation, 0 otherwise. Bugs  C Compiler and Library Page 5-140 isspace Return non-zero if the character is "whitespace" 5.115 Return non-zero if the character is "whitespace" ______ ________ __ ___ _________ __ ____________ *********** * isspace * *********** File name: isspac.mac Usage isspace(c); int c; Description Return non-zero if c is a whitespace character. These consist of space, backspace, newline, tab, and form-feed. The carriage return ('\r') is also included. Bugs  C Compiler and Library Page 5-141 isupper Return TRUE if Upper-case alphabetic argument 5.116 Return TRUE if Upper-case alphabetic argument ______ ____ __ __________ __________ ________ *********** * isupper * *********** File name: isuppe.mac Usage isupper(c); int c; Description Return 1 if c is an Upper-case alphabetic character, 0 otherwise. Bugs  C Compiler and Library Page 5-142 isxdigit Return non-zero if hexadecimal digit 5.117 Return non-zero if hexadecimal digit ______ ________ __ ___________ _____ ************ * isxdigit * ************ File name: isxdig.mac Usage isxdigit(c); int c; Description Return non-zero if C is a valid hexadecimal digit (0-9, A-F, a-f). Bugs This routine is not present in other C libraries.  C Compiler and Library Page 5-143 itoa Integer to Ascii 5.118 Integer to Ascii _______ __ _____ ******** * itoa * ******** File name: itoa.mac Usage char * itoa(value, string) int value; char *string; Description itoa converts the value to a (signed) decimal string. The string is null-trailed. itoa returns a pointer to the trailing null. Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%d", value); Bugs  C Compiler and Library Page 5-144 itoa8 Convert integer to octal Ascii 5.119 Convert integer to octal Ascii _______ _______ __ _____ _____ ********* * itoa8 * ********* File name: itoa8.mac Usage char * itoa8(value, buffer); int value; char *buffer; Description: The value is converted to octal and stored in the buffer. A pointer to the trailing null is returned. Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%o", value); Bugs: This routine does not generate leading zeros. If they are needed, use: sprintf(buffer, "%06o", value);  C Compiler and Library Page 5-145 itoax Convert an integer to hexidecimal Ascii 5.120 Convert an integer to hexidecimal Ascii _______ __ _______ __ ___________ _____ ********* * itoax * ********* File name: itoax.mac Usage char * itoax(value, buffer); int value; char *buffer; Description: Convert the integer to hexidecimal ascii. The string is null-trailed. Values from 10 to 15 (decimal) are represented by "A" to "F". Itoax() returns a pointer to the trailing null. Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%x", value); Bugs:  C Compiler and Library Page 5-146 kbin Single Character Terminal Input 5.121 Single Character Terminal Input ______ _________ ________ _____ ******** * kbin * ******** File name: kbin.mac Usage int kbin(); Description Read one character from the console terminal. The input character is not echoed nor does the program delay until an entire line has been entered. Note the following: This routine is very inefficient, as it requests operating-system service for every character entered. Typing Control/C (or Control/Y on VMS) will cause the program to exit immediately (as if the main() routine exited), closing all files. On RT-11 (native and emulated), the operating system expands to a carriage return line feed sequence. This will be stripped by kbin() to just ('\r' in C). Thus, if the user program reads '\n', a was typed. Note that this is unlike the general C library. Bugs On RSX, this routine requires the command terminal having been assigned as logical unit number 1. In general, the input character will not have been echoed. On RSTS/E and native RT11, the operating system may already have echoed the character if you type the character before the read request has been made.  C Compiler and Library Page 5-147 kbinr Terminal Input Without Wait 5.122 Terminal Input Without Wait ________ _____ _______ ____ ********* * kbinr * ********* File name: kbinr.mac Usage int kbinr(); Description If a character has been typed on the console terminal, return it (without echoing or waiting). If no character is available, kbin() returns -1 (EOF). Note the following: This routine is very inefficient, as it requests operating-system service for every character entered. Typing Control/C (or Control/Y on VMS) will cause the program to exit immediately. On RT-11, the operating system expands to a carriage return line feed sequence. This will be stripped by kbin() to just ('\r' in C). Thus, if the user program reads '\n', a was typed. Note that this is unlike the general C library. Bugs On RSX-11M, this routine depends on the fact that the console terminal was assigned to LUN 1. On RSX-11M and VMS emulation mode, the typed character will not be echoed. On RSTS/E and RT11 modes, it may have already been echoed by the operating system if the terminal user typed before the program requests input.  C Compiler and Library Page 5-148 localtime Build time of day buffer 5.123 Build time of day buffer _____ ____ __ ___ ______ ************* * localtime * ************* File name: localt.mac Usage #include /* Define tm structure */ struct tm * localtime(tvec); long *tvec; /* Time value pointer */ struct tm { int tm_sec; /* Seconds */ int tm_min; /* Minutes */ int tm_hour; /* Hours */ int tm_mday; /* Day of month */ int tm_mon; /* Month 0 .. 11 */ int tm_year; /* Year - 1970 */ int tm_wday; /* Weekday, Sunday == 0 */ int tm_yday; /* Days since Jan 1 */ int tm_isdst; /* Daylight Saving if 1 */ }; Description localtime() converts a Unix time value to a vector of values. Bugs Decus C doesn't correct for time zone or daylight savings time. Leap year isn't done correctly. The routine will fail after Feb 28, 2100. Following Unix precedent, localt returns a pointer to a static buffer.  C Compiler and Library Page 5-149 malloc Allocate and free memory 5.124 Allocate and free memory ________ ___ ____ ______ ********** * malloc * ********** File name: malloc.mac Usage char * malloc(size); /* NULL if no space */ unsigned size; /* Number of bytes */ mfree(p); free(p); char *p; /* Was allocated */ Internal extern char *$$alhd; /* Allocated block list */ mov size,r0 ; Internal call call $$aloc ; to malloc() Return: r0 -> space (or 0), other registers preserved mov pointer,r0 ; Internal call call $$free ; to free() Return: r0 random, other registers preserved Description malloc() allocates the indicated number of bytes, returning a pointer to the first. If the allocation request cannot be satisfied, malloc returns NULL. The program image is expanded as needed. free() and mfree() return a buffer to free space. Nothing is returned. See also the description of realloc() and sbrk(). Internal All free memory is allocated in linked lists which are stored in monotonically linked, noncontiguous areas. Each block has is preceeded by a one word header:  C Compiler and Library Page 5-150 malloc Allocate and free memory pointer to next block + "busy bit" The pointer is to the next following block. The last block points to the first. The "busy bit" will be set if the data in the block is in use. $$alhd points to the first such block. Note that a block need not contain any data. Free space is coalesced during the allocation search. Diagnostics The program may abort if free() is passed a random pointer or if the program writes outside of an area reserved by malloc(). Note that only certain cases are trapped by this test and that free will accept invalid addresses, which will cause mysterious failures. The isalloc() function may be used to test whether a block of memory has been allocated by malloc(). Bugs  C Compiler and Library Page 5-151 maxmin Maximum and Minimum Routines 5.125 Maximum and Minimum Routines _______ ___ _______ ________ ********** * maxmin * ********** File name: maxmin.mac Usage max(a,b) int a; int b; min(a,b) int a; int b; unsigned maxu(a,b) unsigned a; unsigned b; unsigned minu(a,b) unsigned a; unsigned b; Description max() and min() return, respectively, the maximum and minimum of their two arguments, considered as signed integers. maxu() and minu() are the same but consider their arguments to be unsigned. Note: If you are interested in getting the fastest code possible and have some knowledge of the relative sizes of a and b, arrange for a to be chosen most often. (It's unlikely the difference will be noticable in virtually all cases.) Bugs  C Compiler and Library Page 5-152 memdmp Dump memory or registers 5.126 Dump memory or registers ____ ______ __ _________ ********** * memdmp * ********** File name: memdmp.mac Usage memdmp(start, end); /* Memory dump routine */ char *start; /* First to dump */ char *end; /* Last to dump */ regdmp(); /* Register dump */ Internal call regdmp ;Register dump mov #end,-(sp) ;Last address (or first) mov #start,-(sp) ;First address (or last) call memdmp ;Dump memory mov #start,r0 ;First address (or first) mov #end,r1 ;Last address (or last) call $$dump ;Dump memory mov value,r0 ;What to convert mov #buffer,r1 ;Where it goes call $$toct ;Convert it Return: r0 unchanged r1 -> first free byte in buffer r2-r5 unchanged Description Dump registers and/or memory. All registers are preserved. If memdmp is called with a zero argument, the stack will be dumped. Memdmp and regdmp are independent of the C I/O library. However, on RSX, they assume that the console terminal has been assigned as LUN 1.  C Compiler and Library Page 5-153 memdmp Dump memory or registers Bugs Condition codes are not preserved.  C Compiler and Library Page 5-154 msg Print a message on the command terminal 5.127 Print a message on the command terminal _____ _ _______ __ ___ _______ ________ ******* * msg * ******* File name: msg.mac Usage msg(text) char *text; Internal mov #text,r0 call $$msg Description Print a message on the console terminal. This routine does not use the standard library. Return: all registers are preserved. Bugs On RSX, this routine requires the command terminal having been assigned as logical unit number 1.  C Compiler and Library Page 5-155 msize Get Size of a Memory Block 5.128 Get Size of a Memory Block ___ ____ __ _ ______ _____ ********* * msize * ********* File name: msize.mac Usage unsigned int msize(buff) char *buff; Description msize() returns the size of a block of memory allocated by calloc(), malloc(), or realloc(). If buff did not, in fact, come from one of these routines, the program will crash about 75% of the time; the other 25% , nonsense will be returned. (This behavior is due to a simple-minded validation algorithm.) However, buff == NULL is valid and will return 0. Note that the value returned is the amount of memory that malloc() (or whoever) actually allocated, which may not be exactly the same as the program asked for. (Currently, all allocations are rounded up to an even number of bytes.) Bugs Not portable.  C Compiler and Library Page 5-156 mul$l Multiply long * long 5.129 Multiply long * long ________ ____ _ ____ ********* * mul$l * ********* File name: mull.mac Usage long mul$l(a, b); /* long = long * long */ long a; long b; long mul$li(a, b); /* Long = long * int */ long a; int b; Description Multiply the long arguments. This routine is called by the C compiler to compile long multiplies. For EIS, given two longs, A and B, in the word format Ah,As,Al and Bh,Bs,Bl where Ah is the high word, As the sign bit of the low word, and Al the remaining 15 bits of the low order word. Then A * B = Al * Bl + As * Bl * 2**15 + Bs * Al * 2**15 + Al * Bh * 2**16 + Bl * Ah * 2**16 This derivation was provided by Cliff Geschke. Bugs  C Compiler and Library Page 5-157 peek Peek at a location in RSTS/E 5.130 Peek at a location in RSTS/E ____ __ _ ________ __ ______ ******** * peek * ******** File name: peek.mac Usage peek(location) int *location; Description Peek to a location in the RSTS/E monitor. The job will be aborted with a BPT if not running under RSTS/E. Bugs  C Compiler and Library Page 5-158 perror Print Library Error Message 5.131 Print Library Error Message _____ _______ _____ _______ ********** * perror * ********** File name: perror.mac Usage perror(text) char *text; Description An error message is written to stderr, using the current i/o library error (stored in $$ferr). Text is prepended to the message. Diagnostics Bugs  C Compiler and Library Page 5-159 printf Formatted print routine 5.132 Formatted print routine _________ _____ _______ ********** * printf * ********** File name: printf.mac Usage printf(format, arg1, ...) char *format; fprintf(iov, format, arg1, ...) FILE *iov; char *format; char * sprintf(buffer, format, arg1, ...); char *buffer; char *format; $$prnt(format, argvec, iov) char *format; int *argvec[]; FILE *iov; Description printf() converts, formats, and prints its arguments, under control of the first argument, writing output via putchar(). fprintf() writes its output to the indicated file. sprintf() writes its output to the indicated string buffer. $$prnt() is the internal print formatter which is called by printf, etc. sprintf() returns a pointer to the EOS at the end of the output buffer. This is not necessarily transportable. The format argument is a character string which contains two types of objects: plain characters, which are simply copied to the output stream, and conversion specifications, each of which causes conversion and printing of the next successive argument to printf. Each conversion specification is introduced by the character %. Following the %, there may be - an optional minus sign "-" which specifies left  C Compiler and Library Page 5-160 printf Formatted print routine adjustment of the converted argument in the indicated field. - an optional digit string specifying field width; if the converted argument has fewer characters than the field width, it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width. If the field width is specified as '*' or '?', the next argument is used. (Note: '?' is obsolete.) If the width is specified with a leading zero, zeros are used for padding instead of blanks. This zero does NOT imply an octal field width. For example, assume the value 123 is to be printed: %d "123" %5d " 123" %-5d "123 " %05d "00123" - an optional period "." which serves to separate the field width from the next digit string; - an optional digit string (precision) which specifies the number of digits to appear after the decimal point for e- and f-conversion, or the maximum number of characters to be printed from a string. If the precision is specified as '*' or '?', the next argument is used. - a character which indicates the type of conversion to be applied. The conversion characters and their meanings are d Signed-decimal u Unsigned-decimal o Octal X Hexadecimal, 10-15 are represented by A-F x Hexadecimal, 10-15 are represented by a-f The integer argument is converted to decimal, octal, or hexadecimal notation respectively. Any of the conversion characters may be preceeded by 'l' to signal "long" integer argument. Note that the Unix usage of capital letters to represent long arguments is not supported. Note In order to eliminate the very large floating point conversion routines from most programs, a program which requires floating point conversion must request  C Compiler and Library Page 5-161 printf Formatted print routine the double to ascii conversion routine explicitly. The following sequences show how this is done: RSX: TKB task=source,LB:DTOA,LB:C/LB RT11: LINK source,C:DTOA,C:SUPORT,C:CLIB/BOT:2000 If this is not done, any use of the %f %e, or %g conversions will result in an error message. On RSTS/E, the library build procedure creates RTDTOA.OBJ and RXDTOA.OBJ in the library account. ** Floating point support has not yet ** ** been fully implemented. The float ** ** or double value must be the last ** ** or only argument to printf. Only ** ** single-precision conversion is ** ** presently available. ** f The argument is converted to decimal notation in the style "[-]ddd.dd" where the number of d's after the decimal point equals the precision specification for the argument. If precision is missing, 6 digits are given; if explicitly 0, no digits and no decimal point are printed. The argument should be float or double. "%lf" or "%F" must be used to signal "long (i.e. double) argument." This is a restriction of Decus C. e The float or double argument is converted in the style "[-]d.ddde+-dd" where there is one digit before the decimal point and the number after is equal to the precision specified for the argument; if the precision is missing, 6 digits are produced. "%le" or "%E" must be used to signal "long (i.e. double) argument." This is a restriction of Decus C. g Floating point: "%f" format if suitable, else "%e" format. "%lg" or "%G" must be used to signal "long (i.e. double) argument." This is a restriction of Decus C. c The argument character is printed. (Note that 'lc' takes a long integer argument.) r Remote format. The next printf() argument is the format. Note that this is not a subroutine. The current format is not processed further. For example: bug(args) {  C Compiler and Library Page 5-162 printf Formatted print routine error("Error at %r", &args); } This routine might be called as follows: bug("Error %d at %s\n", val, name); %r is not transportable to all implementations of the standard library. It does not word on Vax-11 C, for example. $$prnt may be used as shown below for similar functionality. s The argument is taken to be a string (character pointer) and characters from the string are printed until a null character or until the number of characters indicated by the precision specification is reached; however if the precision specification is 0 or missing all characters up to null are printed. If no recognizable character appears after the %, that character is printed; thus % may be printed by the use of the string %%. In no case does a non-existant or small field width cause truncation of a field; padding takes place only if the specified field width exceeds the actual width. Characters generated by printf() are printed by calling putchar(). $$prnt() is the internal print formatter called by all "top-level" print functions. It is functionally identical to the Unix and Vax-11 C _doprnt() library routine. Unfortunately, the leading '_' conflicts with RSX-11M file services library routine conventions, requiring the use of the Decus C unique "$$" prefix. If your programs wish to call $$prnt, a potentially transportable procedure would be: #ifdef decus $$prnt(format, args, iov); #else _doprnt(format, args, iov); #endif You should assume, however, that _doprnt() is not necessarily present on all implementations of the "standard library." Bugs e, f, and g conversion only work for single-precision floating point. Use of "%lf" etc. is not transportable and may change. It may also cause problems in the C compiler (as the standard says that subroutine calls take double (not short floating) arguments.  C Compiler and Library Page 5-163 profile Print profile data 5.133 Print profile data _____ _______ ____ *********** * profile * *********** File name: profil.mac Usage $$prof(); extern int $$prnl; extern char *$$pfil; Description $$prof is called by the run-time library when the program exits if any functions have been executed that were compiled with the profile option. A profile file is written to file "profil.out". This is defined by a global symbol $$pfil. By setting $$prnl to NULL, the profile file is supressed. By changing the value of $$prnl, the program can control the number of profile entries written on each line. The default value writes 4 entries per line. Changing $$prnl to N writes N entries on each line, simplifing post-processing (sorting) of the data. For example: $$prnl = 0; writes each entry on a separate line. The following example shows how to control the output file name: extern char *$$pfil; ... $$pfil = "ti:"; /* Output to ti: */ $$pfil = NULL; /* No profile output */ Data is written using the format string "%8s %6u". If more than one entry is written to a line, succeeding entries will be preceeded by one space.  C Compiler and Library Page 5-164 profile Print profile data Note that, by writing the data one entry per line, the profile output may easily be sorted either by function name or by frequency count. Bugs  C Compiler and Library Page 5-165 putc Output one character to a file 5.134 Output one character to a file ______ ___ _________ __ _ ____ ******** * putc * ******** File name: putcha.mac Usage putchar(c); char c; putc(c, iop); char c; FILE *iop; Description Putchar() writes one character to the standard output file. Putc() writes one character to the named output file. Normally, the character is returned. EOF is returned on errors. Bugs  C Compiler and Library Page 5-166 puts Output a string to a file 5.135 Output a string to a file ______ _ ______ __ _ ____ ******** * puts * ******** File name: puts.mac Usage puts(s); char *s; fputs(s, iop); char *s; FILE *iop; fputss(s, iop); char *s; FILE *iop; Description puts() writes a string to the standard output. It appends a newline after the string. fputs() writes a string to the indicated file. No newline is appended. fputss() writes a string to the indicated file. A newline is appended. Bugs  C Compiler and Library Page 5-167 putw Output a binary integer to a file 5.136 Output a binary integer to a file ______ _ ______ _______ __ _ ____ ******** * putw * ******** File name: putw.mac Usage putw(word, iop); int word; FILE *iop; Description putw() writes one word to the indicated file. It returns EOF on error, 0 on success Bugs  C Compiler and Library Page 5-168 qset Add memory to the RT11 queue area 5.137 Add memory to the RT11 queue area ___ ______ __ ___ ____ _____ ____ ******** * qset * ******** File name: qset.mac Usage qset(number) int number; /* How many elements */ Description Allocate sufficient memory for the requested number of queue elements. If sufficient memory cannot be allocated, do nothing. Bugs This routine is ignored on RSX.  C Compiler and Library Page 5-169 r50toa Convert Radix-50 to Ascii 5.138 Convert Radix-50 to Ascii _______ ________ __ _____ ********** * r50toa * ********** File name: r50toa.mac Usage r50toa(buff, r5vec, r5cnt); char *buff; /* Output text buffer */ int *r5vec; /* Input rad50 buffer */ int r5cnt; /* How many rad50 words */ Description: Convert r5cnt words of radix 50 data to Ascii. All letters will be in upper-case. The output buffer will not be null-trailed, nor will blank fields be supressed. Bugs  C Compiler and Library Page 5-170 rand Random number generator 5.139 Random number generator ______ ______ _________ ******** * rand * ******** File name: rand.mac Usage long rand() extern long seed; /* Random number seed */ Description Generate a pseudorandom number. The algorithm is: seed = (69069 * seed + 1); return (rand & 0X8FFFFFFF); The algorithm is based on the mth$random function in the VMS common run-time library. Note that the algorithm is prone to nonrandom sequences when considering the next pseudorandom number. Bugs  C Compiler and Library Page 5-171 realloc Reallocate memory 5.140 Reallocate memory __________ ______ *********** * realloc * *********** File name: reallo.mac Usage char * realloc(buff, size); char *buff; /* Buffer from malloc() */ unsigned size; /* New size for buff */ Description Realloc() changes the size of the block pointed to by buff, returning a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. Realloc() also works if buff points to a block freed since the last call of malloc(), realloc(), or calloc(); thus sequences of free(), malloc(), and realloc() can exploit the search strategy of malloc() to do storage compaction. See also the description of malloc(), calloc() and sbreak(). The following program segment illustrates use of realloc() to expand and compact storage. #ifndef vms static char *compact_work; #endif main() { /* * Initialize work element * for compact() */ #ifndef vms compact_work = malloc(1); #endif ... }  C Compiler and Library Page 5-172 realloc Reallocate memory char * compact(old_ptr, new_size) char *old_ptr; int new_size; /* * Reallocate the area allocated to old_ptr, * originally allocated by a call to malloc(), * so that it will contain new_size bytes (which * may be greater or less than the current size). * Return a pointer to the new area. * Note: error handling is not shown. */ { extern char *realloc(); free(old_ptr); #ifndef vms free(compact_work); compact_work = malloc(1); #endif return(realloc(old_ptr, new_size)); } compact_work must not be used on the native vax compiler (Vax-11 C) as the internal free memory buffers are organized in a different and incompatible manner. Diagnostics The program will abort if buff is not the address of a buffer allocated by malloc() or calloc(). Bugs  C Compiler and Library Page 5-173 rewind Rewind a file for re-reading 5.141 Rewind a file for re-reading ______ _ ____ ___ __________ ********** * rewind * ********** File name: rewind.mac Usage rewind(iop); FILE *iop; Description Rewind the indicated file. Return -1 if failure, 0 if ok. On RT11, if the file was opened for output, it is closed and reopened for input. Diagnostics RT11 exits fatally if the file name won't parse. As the filename was stored by fopen(), this probably means that the user program has stored randomly in memory. Bugs  C Compiler and Library Page 5-174 rindex Find Last Instance of a Character in a String 5.142 Find Last Instance of a Character in a String ____ ____ ________ __ _ _________ __ _ ______ ********** * rindex * ********** File name: rindex.mac Usage char * rindex(stng, chr) char *stng; /* String to search in */ char chr; /* Byte to search for */ Description If chr is in stng, return a pointer to the last instance it. If not, return NULL. Bugs Obsolete, use strrchr() instead.  C Compiler and Library Page 5-175 rstsys Execute a RSTS EMT 5.143 Execute a RSTS EMT _______ _ ____ ___ ********** * rstsys * ********** File name: rstsys.mac Usage int rstsys(emt) Description Execute a rsts emt, returning the error code. Bugs  C Compiler and Library Page 5-176 rtemt Execute a RT11 EMT 5.144 Execute a RT11 EMT _______ _ ____ ___ ********* * rtemt * ********* File name: rtemt.mac Usage int rtemt(emt, r0value) Description Execute a rt11 emt after loading r0. Bugs  C Compiler and Library Page 5-177 salloc Allocate local memory 5.145 Allocate local memory ________ _____ ______ ********** * salloc * ********** File name: salloc.mac Usage char * salloc(n); /* NULL if no space */ Description Allocate the requested number of bytes on the run-time stack, returning a pointer to the first byte allocated. The storage will be reclaimed automatically when the function that called salloc() exits. Note that storage so allocated cannot be explicitly freed. salloc() returns NULL if allocating the requested space would cause the run-time stack to go below 1000 octal. Note: it is essential that salloc() be called with a "clean stack". I.e, the program must not execute subr(salloc(10), 20); Instead, it should execute temp = salloc(10); subr(temp, 20); Diagnostics Bugs  C Compiler and Library Page 5-178 sbrk Allocate memory from operating system 5.146 Allocate memory from operating system ________ ______ ____ _________ ______ ******** * sbrk * ******** File name: sbrk.mac Usage char * sbrk(amount) int amount; Description sbrk() allocates the indicated amount of memory from the operating system. The allocation is permanent. Diagnostics NULL is returned if the memory requested is not available. There is no "shortened" return. Bugs Internal Sbrk() does not modify its argument.  C Compiler and Library Page 5-179 scanf Formatted input conversion 5.147 Formatted input conversion _________ _____ __________ ********* * scanf * ********* File name: scanf.mac Usage scanf(fmt, pointer(s)) char *fmt; /* Format string */ fscanf(fd, fmt, pointer(s)) FILE *fd; /* Input file pointer */ char *fmt; /* Format string */ sscanf(buf, fmt, pointer(s)) char *buf; /* Input text buffer */ char *fmt; /* Format string */ $$scan(fmt, argp, iov) char *fmt; /* Format string */ int *ptr[]; /* Pointer vector */ FILE *iov; /* Input file des. */ Description Using the format string, these functions parse the input file (or given text file), storing the results in the pointer arguments. The three user-callable routines differ as follows: scanf Reads from the standard input file. fscanf Reads from the indicated file. sscanf Reads from the text buffer. $$scan() is an internal routine called by the above to actually parse the input text. It is functionally identical to the Unix and Vax-11 C _doscan() routine. Unfortunately, the leading '_' conflicts with RSX file control service routine naming conventions. The format string may contain control characters to direct the conversion of the input textual data: ' ' Blanks, tabs, or newlines are ignored in format  C Compiler and Library Page 5-180 scanf Formatted input conversion strings. To match whitespace, use "%[ \t\n]". x An ordinary character (not %) must match the next input character. % Conversion specifications consist of a '%', an optional '*' (to supress assignment), an optional maximum numeric field width, and a conversion specifier. Unless value assignment was supressed by the '*' format modifier, the next field is converted and stored in the variable pointed to by the corresponding argument. An input field is defined as a string of non-space characters, extending to the first inappropriate character or until the field width (if given) is exhausted. The following conversion characters are specified: % A single '%' is expected in the input, no assignment is done. d An integer of the specified class (decimal, o octal, or hexadecimal) is expected. The x corresponding argument should be an integer pointer. If the format specifer is given in upper-case, or preceeded by 'l', a long integer will be stored. For example, "%ld" is identical to "%D". Leading whitespace will be ignored. A null field is not converted. Scanf() returns a count of the number of fields converted, but does not indicate which fields were ignored. s A character string is expected. The input field will be terminated by a space, tab, or newline. The corresponding argument should point to a buffer large enough to contain the text and a terminating NULL. Leading whitespace will be ignored. c A single character is read. Leading white space is not supressed -- to read the next non-blank character, use "%1s". If a field width is given the corresponding argument is a pointer to a vector of characters and the indicated number of characters are read. e A floating-point number is converted and stored f appropriately. If the format indicator is g capitalized, or preceeded by 'l', a double- precision floating-point number will be stored. The floating-point format is the same as in the C language: an optionally signed string of  C Compiler and Library Page 5-181 scanf Formatted input conversion digits possibly containing a decimal point, followed by an optional exponent field which consists of an 'E' or 'e' followed by an optionally signed integer. [ ] A string not to be delimited by white-space characters. Unless the first character is '^', the format constitutes an acceptance list: the input field is all characters until the first character which is not in the set within brackets. Note that leading whitespace is not ignored. If the first character after the left bracket is '^', the format defines a stop list: the input field is all characters until the first character specified within the bracketed string. The corresponding argument points to a character vector. The result will be null-terminated. Scanf() returns the number of successfully matched and assigned input items. If the end of input was reached, EOF (-1) is returned. For example: main() { register int c; int i; char text[10]; c = scanf("%d%9s", &i, &text); printf("i = %d, text = %s\n", i, text); } If the input line is "150 foobar", the program will print: i = 150, text = foobar Diagnostics Scanf() returns -1 if an end of file (end of string) condition exists and no data was stored. It returns -2 if a palpably incorrect format, such as "%" is encountered. Bugs  C Compiler and Library Page 5-182 screen Screen I/O Primitives 5.148 Screen I/O Primitives ______ ___ __________ ********** * screen * ********** File name: screen.mac Usage scdown() /* Roll screen down */ scerln(line, column) /* Erase to end of line */ int line; /* Line number */ int column; /* Column number */ scerpg(line, column) /* Erase to end of page */ int line; /* Line number */ int column; /* Column number */ char * scget(buff, size, text) /* Prompt and read */ char *buff; /* Returned text */ int size; /* Buffer size */ char *text; /* Optional prompt */ int sclmargin(lmarg) /* Set left margin */ int lmarg; /* New left margin */ scout(line, column, text) /* Write text to screen */ int line; /* Line number */ int column; /* Column number */ char *text; /* Text to write */ scput(oldbf) /* Reset buffer mode */ char *oldbf; /* Previous buffer */ int scset(newbf, size, old) /* Set buffer mode */ char *newbf; /* New buffer */  C Compiler and Library Page 5-183 screen Screen I/O Primitives char size; /* Size of new buffer */ char **old; /* Previous buffer save */ int scsettype(type) /* Force terminal type */ int type; /* Terminal type */ int sctype() /* Return terminal type */ Description Based on the "terminal independent screen procedures" in the VAX/VMS runtime library, these routines provide an efficient, operating-system independent, interface to (DIGITAL) video terminals. They work correctly with VT52 and VT100 (ANSI) terminals and do nothing disasterous if the terminal is not a video terminal. Note that they only work with the user's console (stderr) terminal. The following definitions should be noted: line The line on the screen to which the cursor is to be moved. The top of the screen is line one. If line is less than or equal to zero, the cursor does not move. column The column to which the cursor is to be moved. This value will be offset by the left-margin value (if one is set). The default left-hand margin is column one. If column (after offsetting) is less than or equal to zero, the cursor does not move. text A null-terminated string to be output. If text equals NULL, nothing is output and internal buffers are flushed. The routines are designed to operate in a buffered mode, allowing the program to format an entire screen of information and present this data with one call to the monitor-level I/O service. This is particularily efficient on multi-user or networked systems. The routines scput() and scset() establish and release buffer mode. Buffers can be chained together, allowing a subroutine to establish a buffer independently of its callers. Each buffer must be at least 12 bytes long.  C Compiler and Library Page 5-184 screen Screen I/O Primitives Longer buffers are more efficient. Although multiple buffers can be established, only one is active at any particular time. If a call to scset() establishes a new buffer, the contents of the previous buffer are copied to the new buffer and the previous buffer is set empty. If scput() releases a buffer, its contents are copied to any higher-level buffer. The first call to any routine determines the terminal type. Note that on native RT11, if the screen handler decides that the terminal may be a scope, it will send an "identify" request "/Z" to determine whether it is a VT52 or VT100. If the screen routine decides that the terminal is not a scope, cursor move operations are ignored and text is output to "stderr". If the screen handler decides that the terminal is a VT100, the "Enter ANSI mode" escape sequence will be sent to the terminal. Similarily, if the terminal is thought to be a VT52, the "Enter VT52 emulation mode" sequence will be sent. The screen handler will not record the current mode for subsequent resetting. Screen output will be to the "stderr" device (explicitly the console terminal). Input will be from the "stdin" device. If a local buffer has been established, the screen handler calls operating system service directly, bypassing the "standard" I/O library. This means that output formatting should use sprintf() to format a user buffer which is subsequently output using scout(). Furthermore, the newline '\n' character will not be expanded to a "carriage return/line feed" sequence. It is thus highly recommended that the user program perform all formatting by passing appropriate row and column values to scout(). The following routines are defined: scdown() The cursor is moved up one line on the screen. If the cursor was already at the top line on the screen, all lines are moved down one line, the top line is replaced with a blank, and the data that was on the bottom line is lost. (VMS Lib$Down_Scroll) scerln(line, column) Erase the screen from the indicated (or current) cursor position to the end of the current line. (VMS Lib$Erase_Line)  C Compiler and Library Page 5-185 screen Screen I/O Primitives scerpg(line, column) Erase the screen from the indicated (or current) cursor position to the end of the screen. (VMS Lib$Erase_Page) scget(buff, size, text) Output the prompt text, if given, then flush any buffered text. Read text input by the terminal user (from stdin) to the buffer. Scget() returns NULL on end of file or error. (Scget calls fgetss() to perform the read.) (VMS Lib$Get_Screen) Programs using scget() to read from the keyboard should not use the input redirection capabilities of the C library. sclmargin(lmarg) Define a new left margin (if lmarg is greater than zero). Sclmargin() returns the old lmarg value. After calling sclmargin(), an output request to column one will be written to column lmarg. scout(line, column, text) Move the cursor to the indicated line and column and output the text. If line or column are less than or equal to zero, the cursor is not moved. If text is equal to NULL, the internal buffers are flushed (possibly after cursor movement). (VMS Lib$Put_Screen) scput(oldbf) Scput() terminates the current buffering mode and reverts to the previous mode as specified in the parameter. If oldbuf is NULL, buffering is terminated and the current buffer is flushed to the screen. If oldbuf is not zero, it is taken as the location of a previous buffer (established by calling scset()) and the current buffer is copied into the previous buffer. The previous buffer is then made current. (VMS Lib$Put_Buffer) scset(newbf, size, old) Scset() establishes a new buffer for the screen routines. Newbf is a character array whose size is given in parameter size (Size must be at least 12 bytes.) Old is the address of a word which will be set to the previous buffer (if any). This is used for a  C Compiler and Library Page 5-186 screen Screen I/O Primitives subsequent call to scput(). Scset returns zero if correct, returning -1 if size was less than 12 bytes. (VMS Lib$Set_Buffer). A larger buffer will generally yield a more efficient program as the number of operating system requests will be minimized. For example, for a typeout program, a buffer size of 800 bytes might well be used. scsettype(type) This routine sets the terminal type, overriding the definition supplied by the operating system. scsettype() returns what it thought the type was (as if sctype were called). The type must be one of the following values: 0 Not a video terminal 65 VT52 or VT100 in VT52 mode 97 VT100 in ANSI mode If type has some other value, scsettype() does not change the type. sctype() This routine returns the terminal type. The following types are defined: 0 Not a video terminal 1 Unknown video terminal 1+64 VT52 1+96 VT100 type Note: On intitialization, a VT100 will be forced into VT52 or VT100 mode depending on the determined type. VT100-type terminals include newer terminals such as the VT125. It is not clear whether the algorithm used is correct for terminals developed since these routines were written. Note the following normal use of scset() and scput() char **oldbuf; char mybuf[100]; main() { /* * Setup */ scset(mybuf, sizeof mybuf, &oldbuf);  C Compiler and Library Page 5-187 screen Screen I/O Primitives /* * Usage */ scout(1, 1, "Stuff"); /* * Termination (force out last buffer) */ scout(0, 0, NULL); scput(oldbuf); } Bugs These routines are fairly inefficient if no buffer is supplied. Determining the terminal type turns out to be a somewhat painful process which is different for the various operating systems: On native RSX-11M and VMS compatibility mode, the QIO "get multiple characteristics function" is executed. If the terminal is a scope and can generate escape sequences, it is assumed to be a VT100, otherwise, if it is a scope, it is assumed to be a VT52. On all RSTS/E systems, the executive "get terminal characteristics" request is executed, the determination proceeding as above. On native RT11 systems, a peek sequence described in the RT11 Software Support manual is used to determine whether the terminal is a scope. (This may not work on the XM monitor.) If so, an "/Z" is sent to request identification and various tests are made on the returned text. Note that, if the terminal does not reply to the inquiry, the program will hang. These tests are valid for VT52 and VT100 terminals only. You will have to modify this routine if you have anything else (including a VT125). On RSX-11M systems (even emulated), if a local buffer is established by calling scset(), output will be done using the IO.WAL QIO function. While based on the VMS Run-time library screen I/O primitives, there are a few differences that may be of interest: The VMS library standard assumes that subroutines generally return a status code, permit missing parameters, and return error codes on being presented  C Compiler and Library Page 5-188 screen Screen I/O Primitives with invalid arguments. The routines described here do nothing when arguments are out of range. Also, there are no optional arguments (optionality is provided for by specifing zero or NULL argument values). Where appropriate, arguments have been ordered "line_no, col_no, other". A more significant difference is that the VMS library writes to the standard output device (SYS$OUTPUT: or TT:) while these routines write to the user's terminal (SYS$ERROR or CO:). scget() reads from the standard input.  C Compiler and Library Page 5-189 setcc Trap Control/C (RSTS/E RT11 mode only) 5.149 Trap Control/C (RSTS/E RT11 mode only) ____ _________ _______ ____ ____ _____ ********* * setcc * ********* File name: setcc.mac Usage setcc(function); extern int function(); Description The function is defined as a CTRL/C trap routine. Executing setcc(0) disables CTRL/C trapping. Note: If the routine is reentered (because CTRL/C was typed during the execution of function()), the program aborts. Bugs Runs on RSTS/E RT11 mode only.  C Compiler and Library Page 5-190 setjmp Execute non-local goto 5.150 Execute non-local goto _______ _________ ____ ********** * setjmp * ********** File name: setjmp.mac Usage #include setjmp(env); jmp_buf env; /* Static save buffer */ longjmp(env, val) jmp_buf env; /* Was set by setjmp */ int val; /* Value to return */ Description: These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. Setjmp() saves its stack environment in env for later use by unwind(). It returns 0. Longjmp(env) restores the environment saved by the last call of setjmp(env). It then returns in such a way that execution continues as if the call of setjmp() had just returned. All accessible data have values as of the time setjmp() was called. The return from setexit() will have the specified value. For example: #include jmp_buf env; ... main() { ... if (setjmp(&env) != 0) { err_exit(); /* Longjmp called */ } else { process(); /* Setjmp called */ } ... process() { ...  C Compiler and Library Page 5-191 setjmp Execute non-local goto longjmp(&env); The routine that called setjmp() must still be active when longjmp() is called. Bugs  C Compiler and Library Page 5-192 sleep Delay job a given number of seconds 5.151 Delay job a given number of seconds _____ ___ _ _____ ______ __ _______ ********* * sleep * ********* File name: sleep.mac Usage sleep(delay); int delay; Description Sleep a specified number of seconds. Bugs On RSTS/E, the reader should refer to the description of SLEEP() in the operating system documentation. On native RSX-11M or RSX emulated by VMS, sleep() executes a mark-time (MRKT$) and wait sequence, using event flag 1. On native RT11, sleep() executes a .TWAIT executive request. Sleep flushes stdout and stderr.  C Compiler and Library Page 5-193 sprintf Formatted Numeric Conversion 5.152 Formatted Numeric Conversion _________ _______ __________ *********** * sprintf * *********** File name: sprint.mac Usage char * sprintf(buffer, format, arg1, ...); char *buffer; char *format; Description sprintf() converts and formats its arguments, writing the result to the indicated string buffer. For information on formatting, please refer to the description of printf. sprintf() returns a pointer to the EOS byte at the end of the output buffer. Note, however, that this feature is not transportable to other C implementations. Bugs  C Compiler and Library Page 5-194 sscanf Formatted input conversion 5.153 Formatted input conversion _________ _____ __________ ********** * sscanf * ********** File name: sscanf.mac Usage sscanf(buf, fmt, pointer(s)) char *buf; /* Output buffer */ char *fmt; /* Format string */ Description sscanf() parses the input string, in buf, according to the indicated format descriptor, storing the results in the pointer arguments. It returns the number of successfully assigned input items. See the description of scanf() for further documentation. Diagnostics Sscanf() returns -1 if the end of the input string was detected and no data was stored. It returns -2 if a palpably incorrect format, such as "%" is encountered. Bugs  C Compiler and Library Page 5-195 strcat String Concatenate 5.154 String Concatenate ______ ___________ ********** * strcat * ********** File name: strcat.mac Usage char * strcat(out, in); char *out; char *in; Description Append "in" to "out". Return out. Bugs  C Compiler and Library Page 5-196 strchr Find First Instance of a Character in a String 5.155 Find First Instance of a Character in a String ____ _____ ________ __ _ _________ __ _ ______ ********** * strchr * ********** File name: strchr.mac Usage char * strchr(stng, chr) char *stng; /* String to search in */ char chr; /* Byte to search for */ Description If chr is in stng, return a pointer to it. If not, return NULL. strchr(NULL, anything) returns NULL. See also index(). Bugs  C Compiler and Library Page 5-197 strcmp String Compare 5.156 String Compare ______ _______ ********** * strcmp * ********** File name: strcmp.mac Usage int strcmp(s1, s2); char *s1; char *s2; Description Compare two strings, returning -1 if s1 < s2 0 if s1 == s2 +1 if s1 > s2 Bugs  C Compiler and Library Page 5-198 strcpy String copy 5.157 String copy ______ ____ ********** * strcpy * ********** File name: strcpy.mac Usage char * strcpy(out, in); char *out; char *in; Description Copy "in" to "out". Return out. Bugs It might be more useful if it returned out + strlen(in). (See cpystr()).  C Compiler and Library Page 5-199 streq String Equality Test 5.158 String Equality Test ______ ________ ____ ********* * streq * ********* File name: streq.mac Usage streq(a, b); char *a; char *b; Description Return TRUE if the strings are equal. Bugs  C Compiler and Library Page 5-200 strlen String length 5.159 String length ______ ______ ********** * strlen * ********** File name: strlen.mac Usage int strlen(s); char *s; Description Return the length of the argument string. Bugs  C Compiler and Library Page 5-201 strncat String Concatenate 5.160 String Concatenate ______ ___________ *********** * strncat * *********** File name: strnca.mac Usage char * strncat(out, in, count); char *out; char *in; unsigned int count; Description Append "in" to "out". Return out. At most, "count" bytes are moved from in. Note that "count" does not include the trailing null. Bugs  C Compiler and Library Page 5-202 strncmp String Compare With Count 5.161 String Compare With Count ______ _______ ____ _____ *********** * strncmp * *********** File name: strncm.mac Usage int strncmp(s1, s2, count); char *s1; char *s2; unsigned int count; Description Compare at most count bytes between two strings, returning: -1 if s1 < s2 0 if s1 == s2 +1 if s1 > s2 Bugs  C Compiler and Library Page 5-203 strncpy String Copy With Count 5.162 String Copy With Count ______ ____ ____ _____ *********** * strncpy * *********** File name: strncp.mac Usage char * strncpy(out, in, count); char *out; char *in; unsigned int count; Description Copy "in" to "out". Return out. At most, "count" bytes are moved from in. Note that "count" includes the trailing null. If strlen(in) is less than count, "out" is null-filled. If strlen(in) is greater than count, the output buffer will not be null-trailed. Bugs  C Compiler and Library Page 5-204 strneq String Equality Test With Count 5.163 String Equality Test With Count ______ ________ ____ ____ _____ ********** * strneq * ********** File name: strneq.mac Usage int strneq(s1, s2, count); char *s1; char *s2; unsigned int count; Description Compare at most count bytes between two strings, returning TRUE if the the strings are equal. Bugs  C Compiler and Library Page 5-205 strrchr Find Last Instance of a Character in a String 5.164 Find Last Instance of a Character in a String ____ ____ ________ __ _ _________ __ _ ______ *********** * strrchr * *********** File name: strrch.mac Usage char * strrchr(stng, chr) char *stng; /* String to search in */ char chr; /* Byte to search for */ Description If chr is in stng, return a pointer to the last (rightmost) occurrance of it. If not, return NULL. strchr(NULL, chr) returns NULL. Bugs  C Compiler and Library Page 5-206 swabb Byte swap (argument is a buffer pointer) 5.165 Byte swap (argument is a buffer pointer) ____ ____ _________ __ _ ______ ________ ********* * swabb * ********* File name: swabb.mac Usage swabb(buffer); char *buffer; Description: Return buffer[0] and buffer[1] as a byte-swapped integer. Buffer need not be on any particular byte or word boundary. Bugs  C Compiler and Library Page 5-207 swabi Byte swap, (argument is an integer) 5.166 Byte swap, (argument is an integer) ____ _____ _________ __ __ ________ ********* * swabi * ********* File name: swabi.mac Usage swabi(value); int value; Description Return value byte-swab'ed. Bugs  C Compiler and Library Page 5-208 time Compute time of day 5.167 Compute time of day _______ ____ __ ___ ******** * time * ******** File name: time.mac Usage long time(0); long time(tloc); long *tloc; Internal call $$time Description time returns the time of day in seconds. If tloc is non-null, the return value is also stored in the place to which tloc points. The value is the time since midnite, Jan 1, 1970, measured in seconds. Internal $$time is called by time and ftime. It returns the time value in registers r0 and r1, and the number of ticks in the current second in r2. R3 and r4 are modified. On RSX, $$time refreshes $$tick. Bugs The Unix time function returns GMT. This function returns local time. The leap year algorithm is only accurate in the range 1970 <= year < 2100  C Compiler and Library Page 5-209 toascii Convert to 7-bit Ascii 5.168 Convert to 7-bit Ascii _______ __ _____ _____ *********** * toascii * *********** File name: toasci.mac Usage toascii(c); int c; Description Remove the parity bit from c. Bugs  C Compiler and Library Page 5-210 tod Compute time of day 5.169 Compute time of day _______ ____ __ ___ ******* * tod * ******* File name: tod.mac Usage long tod(0); long tod(tloc); long *tloc; Description tod() returns the time of day in seconds. If tloc is non-null, the return value is also stored in the place to which tloc points. tod() is fairly fast. time() computes the "Unix time" but is much slower and larger. Bugs  C Compiler and Library Page 5-211 tolower Convert upper-case to lower-case 5.170 Convert upper-case to lower-case _______ __________ __ __________ *********** * tolower * *********** File name: tolowe.mac Usage tolower(c); int c; Description If c is a upper-case alphabetic, return it's lower-case equivalent. Otherwise, return c. Bugs  C Compiler and Library Page 5-212 toupper Convert lower-case alphabetic to upper-case 5.171 Convert lower-case alphabetic to upper-case _______ __________ __________ __ __________ *********** * toupper * *********** File name: touppe.mac Usage toupper(c); int c; Description If c is a lower-case alphabetic, return it's upper-case equivalent. Otherwise, return c. Bugs  C Compiler and Library Page 5-213 trace Profile support entry module (with trace) 5.172 Profile support entry module (with trace) _______ _______ _____ ______ _____ ______ ********* * trace * ********* File name: pcsv.mac Usage #include extern FILE *$$flow; $$flow = fopen("trace.out", "w"); /* or $$flow = stderr; to trace to the console */ ... $$flow = NULL; /* Turn off flow trace */ Internal jsr r5,pcsv$ .word name ; Pointer to name Where name has the structure: name: .word 0 ; Counter .asciz /name/ ; function name Description This module is called whenever a function that was compiled with the profile option is executed. It checks that the stack will remain above 600 octal when the function executes and optionally prints a flow-trace. If $$flow is set to a file descriptor, the function name, location the function is called from, and the calling environment, are printed on each call to a function compiled with the profile option. The output format is: function_namecallerenvironment Where function_name is the name of the function being called, caller is the address of the calling program (actually, the return address), and environment is the R5 argument pointer (for local addressing within the  C Compiler and Library Page 5-214 trace Profile support entry module (with trace) routine being called). The information will be written to $$flow with a newline before and after. If profiling has been enabled and the program exits via error() or via an operating-system trap (such as an illegal memory reference), a register dump and subroutine trace will be written to stderr. See the description of calltrace() for details. Internal See csv$ for details of the calling environment. When this routine is entered for the first time, it sets up to intercept synchronous system traps, and loads the error exit address and profile pointer. The trap service routines are in the "traps" module. See the description there for more information. Bugs  C Compiler and Library Page 5-215 traps Operating system trap handlers 5.173 Operating system trap handlers _________ ______ ____ ________ ********* * traps * ********* File name: traps.mac Usage Internal $$sstt:: ; RSX synchronous trap ; vector $$t410:: ; RT11 Entry after traps ; to vectors 4 and 10 Description This module contains code which is executed after a synchronous trap is detected by the operating system. All such traps are regarded as fatal errors and the program will be terminated. This code is enabled by executing any function, such as main(), for which profiling was enabled when the function was compiled. The following traps are processed: Illegal memory reference (trap through vector 4) Illegal instruction (trap through vector 10) BPT (assuming a debugging aid is not present) IOT Illegal TRAP (this may be a Fortran error) Illegal EMT (RSX only) Floating point exception (RSX only) Memory management violation Before exiting to the operating system, the registers at the time the trap occurred will be written, in octal, to stdout. Note also that a calling sequence traceback will be written to stdout by error(). If a trap occurred, the program will exit to the operating system with a "severe error" status. Note that some errors, such as stack overflow or random  C Compiler and Library Page 5-216 traps Operating system trap handlers jumps into the operating system, may cause the C program to be terminated without the C library regaining control. Internal The first call to pcsv$ will initialze trapping. On RSX11-M, the SVTK$ executive service will be called. On RT11, the .tprset monitor request will be executed. As .trpset only traps illegal memory reference (trap to 4) and illegal instruction (trap to 10), the other interesting vectors are initialized by absolute references (.ASECT). Diagnostics Bugs Internal Don't forget to handle floating-point when it's implemented.  C Compiler and Library Page 5-217 ungetc Push back a character onto an input file 5.174 Push back a character onto an input file ____ ____ _ _________ ____ __ _____ ____ ********** * ungetc * ********** File name: ungetc.mac Usage ungetc(c, iop); char c; FILE *iop; Description Push one character back on the indicated stream. Bugs  C Compiler and Library Page 5-218 unwind Execute non-local goto 5.175 Execute non-local goto _______ _________ ____ ********** * unwind * ********** File name: unwind.mac Usage setexit(); unwind(); Description: These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. setexit() saves its stack environment in a static place for later use by unwind(). It returns 0. Unwind() restores the environment saved by the last call of setexit(). It then returns in such a way that execution continues as if the call of setexit() had just returned. All accessible data have values as of the time unwind() was called. The return from setexit() will have the value 1. For example: if (setexit()) { /* Unwind called */ } else { /* Setexit setup called */ } The routine that called setexit() must still be active when unwind() is called. Bugs Obsolete -- use setjmp/longjmp instead.  C Compiler and Library Page 5-219 wdleng Expensive way to say sizeof(int) 5.176 Expensive way to say sizeof(int) _________ ___ __ ___ ___________ ********** * wdleng * ********** File name: wdleng.mac Usage wdleng() Description Return word length in bits. Bugs Assuming 8-bit bytes, this may be replaced by: #define wdleng() (sizeof (int) * 8)  C Compiler and Library Page 5-220 wrapup Dummy routine called on exit 5.177 Dummy routine called on exit _____ _______ ______ __ ____ ********** * wrapup * ********** File name: wrapup.mac Usage wrapup() Description This routine (which does nothing) is called on exit if the user's program does not provide a wrapup() routine. Wrapup will be called only once. Bugs  C Compiler and Library Page 5-221 zero Clear a block of memory 5.178 Clear a block of memory _____ _ _____ __ ______ ******** * zero * ******** File name: zero.mac Usage zero(addr, nbytes); char *addr; unsigned int nbytes; Description: Clear the block of core. No value is returned. Bugs  CHAPTER 6 LIBRARY HEADER FILES This chapter contains descriptions of the standard header files that are used by C programs and libraries. In addition, descriptions of internal routines are provided. These files are included in your program source by a pre-processor command of the form: #include  C Compiler and Library Page 6-2 ctype Character test macros and global definitions 6.1 Character test macros and global definitions _________ ____ ______ ___ ______ ___________ ********* * ctype * ********* File name: ctype.h NAME: ctype -- Character test macros and global definitions SYNOPSIS: #include DESCRIPTION: This module defines a set of character test and manipulation macros (or, on Decus C, functions) that allow classification and modification of Ascii characters. If the C compiler supports macros with arguments, the following are defined: isupper(c) /* Upper case alphabetic */ islower(c) /* Lower case alphabetic */ isalpha(c) /* Alphabetic in any case */ isdigit(c) /* Decimal digit */ isalnum(c) /* Alphabetic or digit */ isxdigit(c) /* Hexadecimal digit */ isspace(c) /* Space or tab */ ispunct(c) /* Punctuation */ isgraph(c) /* Visible character */ isprint(c) /* Printable character */ iscntrl(c) /* Control character */ isascii(c) /* 7-bit Ascii character */ _toupper(c) /* Lower case convert to Upper */ _tolower(c) /* Upper case convert to Lower */ toascii(c) /* Remove eighth (parity) bit */ Note that _toupper() and _tolower() must not be used with arguments that have side effects, such as _toupper(*ptr++); Use the functions toupper() and tolower() instead. BUGS:  C Compiler and Library Page 6-3 fps Bit definitions for the floating point status word 6.2 Bit definitions for the floating point status word ___ ___________ ___ ___ ________ _____ ______ ____ ******* * fps * ******* File name: fps.h NAME: fps -- Bit definitions for the floating point status word SYNOPSIS: #include DESCRIPTION: This module defines common definitions for the FP-11 floating point status word. The following are defined: FER 0100000 Floating error (sense/reset) FID 0040000 Disable all interrupts FIUV 0004000 Interrupt on undefined variable FIU 0002000 Interrupt on underflow FIV 0001000 Interrupt on overflow FIC 0000400 Interrupt on int. conv. error FD 0000200 Double precision mode FL 0000100 Long integer mode FT 0000040 Chop mode FN 0000010 Floating negative (sense) FZ 0000004 Floating zero (sense) FV 0000002 Floating overflow (sense) FC 0000001 Floating carry (sense)  C Compiler and Library Page 6-4 initial Specify Initializers and Finalizers 6.3 Specify Initializers and Finalizers _______ ____________ ___ __________ *********** * initial * *********** File name: initia.h NAME: initial -- Specify Initializers and Finalizers SYNOPSIS: #include INITIAL { initial-code-block }; FINAL { final-code-block }; DESCRIPTION: The macros defined in this module provide a facility for module-specific initialization and finalization code. The code in the initial-code-block is called as a normal C function before main() is called; the final-code-block is called on exit, just after wrapup(). Neither call passes any arguments. Any number of modules in an image may independently declare initializers or finalizers; all of them will be called at startup or exit. However, it is impossible to predict what order the calls will be made in, and programs should not rely on any particular ordering. A typical use of initializers and finalizers is the following: Suppose you have a package that supports access to some on-disk data base; a user of the package will call a lookup and an update function. The file containing the data base must be opened before any operations on it can take place, and it should be closed when the program is finished. (Assume that the package maintains some sort of resident buffer which it must flush.) There are two conventional approaches to solving this problem: Have the lookup and update functions check the file on each call, and open it if necessary - which could be quite expensive if they are very small  C Compiler and Library Page 6-5 initial Specify Initializers and Finalizers functions, and in any case does not solve the problem of properly closing the file - or have the main program call an initialization and finalization function at the proper time. The problem with this latter approach is lack of modularity - the main program ought not to have to know that the module needs initialization or finalization. The solution using these macros is straightforward. The defining module includes the calls: INITIAL { open-the-data-base }; FINAL { flush-buffers-and-close-the-data-base }; The wrapup() function is treated like a built-in finalizer; however, it is guaranteed to execute before any other finalizers. (The module defining wrapup() may declare an initializer or finalizer if it wishes; it will be treated just like all other initializers and finalizers.) If any finalizer (or wrapup()) calls exit(), the program exits immediately. Notes: Using INITIAL will declare a static function named $init$(), and a (char *) named $init_; similarly, FINAL will declare $finl$() and $finl_. Also, both INITIAL and FINAL generate dsect commands. Since C provides no way to "remember" the current dsect, both macros issue a dsect "" command when they are done, restoring the C default dsect. While it is a poor idea to write code that depends on the order in which initializers and finalizers are executed, this can be useful information to have for debugging. Execution is always in the order that the modules involved were examined by the task builder or linker. When the modules are named explicitly, this will just be the order in which they were named. When the modules come from a library, it will be extremely difficult to predict the order in which they will be extracted and linked in. Warning: While initializers and finalizers provide some modularity to package initialization and finalization, they are not a panacea. For example, if package A calls routines in package B from within its initializers, and package B also declares initializers, the correct functioning of a program that includes both - hence, of any program using package A - will be problematical.  C Compiler and Library Page 6-6 initial Specify Initializers and Finalizers INTERNAL: The macros operate by leaving a list of (pointers to) functions to be called in psects $INIT$ and $FINL$. In order to be able to determine the beginning and end of these psects, the psects $INIT, $FINL, $INIT., and $FINL., are also reserved. These psects must not actually contain any data; they exist solely to provide well-defined endpoints to the initialization and finalization list. The names are consecutive in alphabetical sequence, so the Task Builder will place them in order. The RT11 Linker, however - and the Task Builder with the /SQ switch - place psects in the order they are encountered. Since it impossible to predict what order the various modules will be seen by the linking program, it is essential that EVERY module that refers to any of these psects refer to the two related ones as well, and in the correct order. BUGS: Requires the DECUS C dsect commands; hence, very non-portable. It may be possible to provide the same functionality using different techniques; if not, what's wrong with your implementation? AUTHOR: Jerry Leichter  C Compiler and Library Page 6-7 rtime Define time buffer structure for $$rtime() 6.4 Define time buffer structure for $$rtime() ______ ____ ______ _________ ___ _________ ********* * rtime * ********* File name: rtime.h NAME: rtime -- Define time buffer structure for $$rtime() SYNOPSIS: #include ... struct TIME buffer; DESCRIPTION: This header file defines the structure of the time buffer used by the standard library $$rtime() function (which is unique to Decus C). It is defined as follows: struct TIME { int year; G.TIYR year - 1900 int month; G.TIMO Jan. = 1 int day; G.TIDA int hour; G.TIHR 00 .. 23 int minute; G.TIMI 00 .. 59 int second; G.TISC 00 .. 59 int tick; G.TICT 00 .. tsec-1 int tsec; G.TICP tick/second }; BUGS: Oboslete, use time() and localtime() instead.  C Compiler and Library Page 6-8 setjmp Define buffer for setjump() and longjump() 6.5 Define buffer for setjump() and longjump() ______ ______ ___ _________ ___ __________ ********** * setjmp * ********** File name: setjmp.h NAME: setjmp -- Define buffer for setjump() and longjump() SYNOPSIS: #include DESCRIPTION: This defines the jmp_buf array that is used for the setjmp() and longjmp() functions. BUGS:  C Compiler and Library Page 6-9 stdio Definitions for standard i/o library 6.6 Definitions for standard i/o library ___________ ___ ________ ___ _______ ********* * stdio * ********* File name: stdio.h NAME: stdio -- Definitions for standard i/o library SYNOPSIS: #include DESCRIPTION: should be included in the assembly of all C programs that use the standard i/o library (fopen(), getc(), printf(), etc.) It defines the following: FILE The i/o routines use and return pointers to objects of this type. NULL I/O routines signal "rejection" by returning a null pointer. EOF The get character routine returns this value to signal end of file. TRUE The value 1. FALSE The value 0. EOS The "end of string" marker: '\0'. IO_SUCCESS Normal exit to operating system. IO_WARNING "Warning error" exit to operating system. IO_ERROR "Error" exit to operating system. IO_FATAL "Severe error" exit to operating system. stdin The "standard" input file. Normally the user's terminal; it may be redirected.  C Compiler and Library Page 6-10 stdio Definitions for standard i/o library stdout The "standard" output file. Normally the user's terminal; it may be redirected. stderr The "error" output file. It will always write to the user's terminal. DIFFERENCES FROM UNIX: FILE is defined as a "typedef struc", rather than a #define. The i/o structure is considerably different from Unix. It is, however, arranged so that reasonable compatibility may be attained. Specifically, things which have the same name are used for the same purpose, and located in the same place within the I/O structure. ACCESSING THE FDB ON RSX MODES: The FDB (file data block) is the primary means of communication between the C I/O library and the RSX file control services modules. It contains file and record format information as well as pointers and counters for accessing data in the file. It is highly recommended that you do not access this information directly. Should you need to do so, the following may be done: extern char *F_RTYP; /* F.RTYP (char) in fdb */ extern char *F_SEQN; /* F.SEQN (int) in fdb */ ... fd = fopen("file.nam", "r"); /* * Set rtyp to the record type, stored as a * byte at offset F.RTYP */ rtyp = fd->io_fdb[(int) &F_RTYP] & 0377; /* * set seqn to the sequence number (printfile * fixed header), stored as an integer at * offset F.SEQN. */ seqn = *((int *) &fd->io_fdb[(int) &F_SEQN]); The somewhat messy use of casts and addressing allows the program to use the value of F.xxx stored in the RSX system library. BUGS: TRUE, FALSE, and EOS are not present in on some other C systems. If you compile with the /r switch (-r on RSX modes) or #define rsts before #include , a native RSTS/E I/O vector will be defined which is neither fully supported nor fully implemented.  C Compiler and Library Page 6-11 time Define time buffer structure for localtime() 6.7 Define time buffer structure for localtime() ______ ____ ______ _________ ___ ___________ ******** * time * ******** File name: time.h NAME: time -- Define time buffer structure for localtime() SYNOPSIS: #include ... extern struct tm *localtime(); DESCRIPTION: This header file defines the structure of the time buffer used by the standard library localtime() function. It is defined as follows: struct tm { int tm_sec; /* Seconds */ int tm_min; /* Minutes */ int tm_hour; /* Hours */ int tm_mday; /* Day in month */ int tm_mon; /* Month */ int tm_year; /* Year */ int tm_wday; /* Weekday */ int tm_yday; /* Days since Jan 1 */ int tm_isdst; /* Daylight Savings = 1 */ }; extern struct tm *localtime(); BUGS: Unix V7 changed the tm_isday to tm_isdst. Thanks guys.  C Compiler and Library Page 6-12 timeb Define timeb buffer structure for ftime() 6.8 Define timeb buffer structure for ftime() ______ _____ ______ _________ ___ _______ ********* * timeb * ********* File name: timeb.h NAME: timeb -- Define timeb buffer structure for ftime() SYNOPSIS: #include ... extern long ftime(); DESCRIPTION: This header file defines the structure of the timeb buffer used by the standard library ftime() function. It is defined as follows: struct timeb { long time; unsigned milltim; short timezone; short dstflag; }; The time value is identical to the value returned by the time() function. Milltim is the number of milliseconds in the current second. Timezone indicates the number of minutes past GMT in the current time zone (zero for Decus C) and dstflag is set if Daylight Savings Time is in effect.  APPENDIX A IMPLEMENTATION A.1 Overview ________ This document describes the Decus C distribution and discusses its implementation on RSTS/E, RSX-11M, RT-11, and VAX/VMS. A.2 Distribution ____________ NOTE The following is in a state of change. The most likely strategy is to have several kits: 1. VMS backup format at 1600 bpi built on a VMS V3.2 system. This will contain both source and compiled images. 2. DOS (FLX) format (source only) on two 1200 foot magtapes at 800 or 1600 bpi. This will contain source files only. 3. RT11 RL02 disk containing a built system and sources stored in "archive" format. 4. RT11 RX01 disk containing built images only -- no sources. Suggestions for improvements are welcome. The master source tape (DOS FLX) was generated on a VAX/VMS system. All files contain readable Ascii text. All executable images were generated by supplied command files. The compiler and run-time library, accounts [5,1] through [5,7], comprise a compiler and run-time system for the C language. The compiler was written by David G. Conroy, and modified by Martin  C Compiler and Library Page A-2 Getting on the Air with Decus C Minow, Robert B. Denny, Clifford Geshke, and several others. The run-time libraries for RSX-11M and RT-11 were written by Martin Minow with help from many friends. In addition, there are several executive interface libraries: one for RSX-11M by Robert B. Denny, one for RSTS/E by Jim Burrows, and one for Vax/VMS (for interface with Vax-11 C) by Martin Minow. There is also a portable math library by Fred Fish. The program library, accounts [6,1] through [6,7], offers a collection of tools, games, and other programs, mostly written in C. They are not needed for installation of the compiler (although several programs in the tools account, such as KWIK, are used to build the documentation.) In general, you should be aware that only the tools in [6,1] are tested. The distribution account numbers were originally chosen so as to be identical under RSX-11M (octal) and RSTS/E (decimal). If the C language system is not stored in the above accounts, the implementor on RSTS/E will have to edit command files to define the proper accounts. The GETCMD and BUILD programs may be useful in this regard. [5,1] Command procedures, documentation source, etc. [5,2] Documentation. [5,3] Compiler and assembler source. [5,4] Common (non-I/O) library source. [5,5] I/O library source and command files. [5,6] Native RSTS/E interface library. [5,7] Native RSX-11M interface library. [6,1] "Software tools." [6,2] Miscellaneous programs -- games and stuff. [6,3] Cross-assemblers for several micro-computers. [6,4] Lexical analyser generator. [6,5] Pieces of a standard library in C [6,6] Useful subroutines in C. [6,7] Vax/VMS interface library. The two-tape distribution contains accounts [5,*] on one (full) tape and accounts [6,*] on the second (2/3 full) tape. Each account contains a file named README.nnn describing the contents of the account. For example, the README file in account [5,1] is named README.501.  C Compiler and Library Page A-3 Getting on the Air with Decus C A.3 Command File Conventions _______ ____ ___________ Command files used to build the C compiler and run-time library follow the following standard: V????? VAX/VMS indirect command file X????? RSX-11M file for the RSTS/E RSX emulator R????? RT-11 file for the RSTS/E RT-11 emulator M????? RSX-11M indirect command file T????? RT-11 indirect command file .CMD RSTS/E indirect command files, RSX-11M indirect command files, and indirect command files for MAC.TSK and MACRO.SAV. .COM RT-11 or VMS indirect command files .TKB Task-builder indirect command files .ODL Task-builder overlay descriptor commands .EIS [RT11.EIS only] hardware EIS configuration Command files used to build tools and C-language libraries follow the following convention: VN???? Use the native Vax-11C compiler only. VX???? Use Decus-C (RSX compatibilitye) on Vax/VMS. VB???? Use either, selecting the compiler at command invocation. RX???? RSTS/E RSX-11M emulation mode. RT???? RSTS/E RT-11 emulation mode. M???? RSX-11M native. T???? RT-11 native.  C Compiler and Library Page A-4 Getting on the Air with Decus C A.4 Distribution Contents in Detail ____________ ________ __ ______ [5,1] [.command] Command Files and Documentation This account contains documentation source files (.rno), kit building command files, and a few things that didn't fit anywhere else. This includes a number of special-purpose command files used to develop the C language system (such as FORK.COM, BATCH.COM, and TOOL.COM) which may serve as models for your own needs. It also contains the source for CRUN.BAS, used on RSTS/E systems to pass arguments to C programs and source for CCN, used to compile and assembler C programs on native RSX-11M. A full build of the Decus C system may be effected by executing RBUILD.CMD on RSTS/E (requires privileges) or VBUILD.COM on VAX/VMS. Either command requires about two hours to complete. At least 2000 free blocks of disk space is necessary on the default (public) disk. Note that the build will abort if the RSX LBR or TKB programs cannot obtain sufficient contiguous disk space. The RGTDOC.CMD or VGTDOC.COM command files build a new documentation kit. To build the documentation, proceed as follows: 1. Build the compiler and libraries. 2. Build the tools. 4. Use GETRNO to create library runoff files -- see VGTDOC.COM or RGTDOC.CMD. 5. Use RNO.TSK to build documentation on RSX-11M or RSTS/E, or use RUNOFF to built the library on VMS V2.0. 6. If on RSTS/E or VMS, execute FIXDOC to repair .DOC files after RNO.TSK or RUNOFF.EXE has finished messing them up. (See the gory details in RGTDOC.CMD and VGTDOC.CMD.) The GETCMD.C and BUILD.C programs were used to build command files for compilation and network file transfer. See the tool documentation or examine some command files for more information. Run-time library command files were built using the RLBCMD.CMD (RSTS/E) or VLBCMD.COM (VMS) command files. Tool command files were built using the BTOOLS.COM or RTOOLS.CMD command files. [5,2] RSTS/E only  C Compiler and Library Page A-5 Getting on the Air with Decus C On some distributions (but not the Decus submission), this account contains the running system for RSTS/E and save images for RT-11. It is never needed on VMS. Any file residing in this account has been generated from source stored in other accounts. The VMS kit read/write command procedures reference account [5,2] only to copy documentation to and from magtape. Note that CC.DOC, AS.DOC, CBUGS.DOC, CLIB.DOC, and WIZARD.DOC are in this account on all distribution kits. This account is the only one that may contain binary files. Consequently, the RSX-11M interface library, CX.OLB, is stored here. It is needed only on native RSX-11M systems. RSX-11M users should be warned that CX.OLB was generated on a VAX/VMS system. CX.OLB is built from a command file in [5,7]. Note that some subroutines will not assemble on RSTS/E or early versions of RSX-11M as the associated macros are not present in the system macro library. [5,3] [.comp] Compiler source This account contains the source and build files for the compiler (CC????.MAC), assembler (AS????.MAC), and the compiler support library (L?????.MAC). The support library is a stripped-down variant of a very early version of the standard library, which is conditionally compiled for RSX or RT-11 flavor I/O support. It is not particularily efficient. To build the compiler, edit RSX.MAC and RT11.MAC to suit your particular hardware needs and execute the CC build command file: @ VMAKCC.COM On VMS ATPK XMAKCC.CMD On RSTS/E RSX mode ATPK RMAKCC.CMD On RSTS/E RT-11 mode @ MMAKCC.CMD On RSX native mode @ TMAKCC.COM On RT-11 native mode Then, build the assembler: @ VMAKAS.COM On VMS ATPK XMAKAS.CMD On RSTS/E RSX mode ATPK RMAKAS.CMD On RSTS/E RT-11 mode @ MMAKAS.CMD On RSX native mode @ TMAKAS.COM On RT-11 native mode [5,4] [.otscom] Common Library  C Compiler and Library Page A-6 Getting on the Air with Decus C This account contains the "common" run-time library source. These files have no I/O or operating-system dependencies. (Note that a few reference library routines to print error messages.) Several modules are called by direct code generation sequences (e.g., the EIS support routines). Command files are stored in [-.OTSIO] ([5,5]). [5,5] [.otsio] I/O library This account contains I/O dependent run-time library source files. These files conditionally compile to generate code for either RSX-11M or RT-11 operating system support. You should be warned that several modules contain essentially two totally distinct subroutines. Internally-called routines are in IO????.MAC. INIT.MAC contains the run-time startup program, which is very system dependent. It also contains some code which is specific to particular operating system releases. To build a library, invoke the appropriate command procedure, using the format described above: @ VMAKLB.COM On VMS ATPK XMAKLB.CMD On RSTS/E RSX mode ATPK RMAKLB.CMD On RSTS/E RT-11 mode @ MMAKLB.CMD On RSX native mode @ TMAKLB.COM On RT-11 native mode [5,6] [.rstslb] RSTS/E Interface Library RSTS/E operating-system dependent subroutines allowing access to RSTS/E executive services by C programs. Many are written in C. They are not as well documented (or written) as they might be. [5,7] [.rsxlib] RSX-11/M Interface Library An interface library to the RSX-11M executive. It is not known what parts of this library work on VMS or RSTS/E emulation modes. This library will not assemble on RSTS/E V7.0 as the distributed system macro library lacks certain executive service macros. [6,1] [.tools] Software Tools C tools. See [.tools]readme.601 for details. The following command files are provided: V?TOOL.COM Vax/VMS: VNTOOL uses the native compiler VAX-11C; VXTOOL uses Decus C; and VBTOOL allows selection of either.  C Compiler and Library Page A-7 Getting on the Air with Decus C R?TOOL.CMD RSTS/E: RXTOOL uses RSX emulation mode, while RTTOOL uses RT11 emulation mode. TTOOL.COM Native RT11. MTOOL.CMD Native RSX-11M. The command files were built by executing BUILD.C for all tools. It is highly recommended that, when you need to recompile a tool, you build the command file using BUILD. For example, to build a command file for GREP on your current operating system, you need only execute: build grep.c >grep.cmd On VMS, the TOOL.COM command file may be used to build a tool by running BUILD to create a command file which is then executed. Note that the RSTS and VMS commands refer to logical devices (BIN:) that, on VMS, are defined externally to the build process. [6,2] [.misc] Toys and Other Stuff Toys, half baked ideas, and other stuff. See [.misc]readme.602 for details. Command files are provided to build COOKIE on RSTS/E and VMS. Some of these files haven't been touched in years. [6,3] [.cross] Cross Assemblers A variety of cross assemblers. See [.cross]readme.603 for details. This account also contains a copy of the 8080 C compiler printed in Dr. Dobbs Journal, March 1980. Again, little recent debugging. Files in this account are stored in archives. To build a cross assembler, you should first extract the relevant files. These have not been extensively tested. [6,4] [.lex] Lexical Analyser A lexical-analyser generator written by Charles Forsyth. The standard build command files will create compiler command files. [6,5] [.libc] Library in C The first pieces of a "standard" library, implemented in C. Currently, the str??? and is??? routines, a few floating-point routines, and some pieces of printf are present. It is hoped that this account will eventually  C Compiler and Library Page A-8 Getting on the Air with Decus C replace [.OTSCOM] and most of [.OTSIO] in the future. Note that, in the first Decus C distribution, this account contained a machine-independent microcomputer cross assembler. Those routines are now stored in the "cross assembler" directory in an archive). [6,6] [.useful] Useful subroutines A library of useful subroutines written in C. [6,7] [.vaxlib] VAX/VMS Interface Routines Interface routines for use with Decus C programs which are being transported to the native VMS C program product. This library predated the released version of Vax-11 C and may contain modules that have been superseded by the distributed Vax-11 C run-time library. Decus C tools must be linked together with this library in order to access routines, such as fwild(), that are not present in the Vax-11 C library. Note especially that the fact that a routine exists in this library (or that a tool compiles under Vax-11 C) does not imply that the tool or routine has been tested. If you blindly install this library, you are asking for trouble. A.5 Installation Overview ____________ ________ NOTE WARNING If you already have Decus C, please backup all files and zero all accounts before copying this distribution to disk. Several files that were on the previous Decus distribution are not on this tape. If you are installing C for the first time, you should print all "README.???" files, the compiler and library/support documentation files, NEWS.DOC, CC.DOC and WIZARD.DOC (in [5,2]), RSX.MAC, RT11.MAC, RT11.EIS, and the command files for your operating system. NOTE WARNING The RT11.MAC and RSX.MAC command files, as distributed, assume the existance of the SXT instruction. This instruction is not present on some early models of the PDP-11. If C programs or libraries  C Compiler and Library Page A-9 Getting on the Air with Decus C are to run on a PDP-11/20, PDP-11/04, PDP-11/05, or on a PDP-11/40 without EIS, the macro header files must be edited to define C$$SXT = 0 before building the compiler or library. Beware, non-SXT compilation hasn't been tested for quite a while. If your system does not have EIS, you can make "no EIS" standard by editing RSX.MAC and RT11.MAC to set symbol C$$EIS to zero. The native RSX build command file inquires whether SXT and EIS defaults must be set. A.5.1 Installation on RSTS/E ____________ __ ______ This installation procedure presupposes RSTS/E V7.1 or later. If you are running on a V6 release, you will have to edit the command files, converting them to batch control files. You may also need to edit SUPORT.MAC, INIT.MAC, FWILD.MAC, and SBREAK.MAC in the run-time library as these routines presuppose executive services that were added with the V7.0 release. Decus C does not require "large files" or other optional RSTS/E features. While the C compiler and run-time libraries generally do not require privileges, you will need privileges to perform a few installation-support functions: Creating accounts. Copying files to a specific account. Installing CCL's and system-wide logicals. Create the various accounts, [5,1] through [5,8] and [6,1] through [6,7]. The accounts may be created on a private disk. Then, copy the distribution tape to these accounts: PIP disk:[*,*]<40>=tape:[*,*] File CX.OLB may be in some distributions. It is not needed for RSTS/E systems and should be deleted. The system manager should add the following commands to your system startup command file (before executing RBUILD): RUN $UTILTY ADD LOGICAL disk:[account] C ! define C logical CCL XCC-=C:CC.TSK;0 ! RSX CC compiler CCL XAS-=C:AS.TSK;0 ! RSX AS assembler  C Compiler and Library Page A-10 Getting on the Air with Decus C CCL CC-=C:CC.SAV;8220 ! RT-11 CC compiler CCL AS-=C:CC.SAV;8220 ! RT-11 AS assembler CCL CRUN-=C:CRUN.*;30000 ! Turn CCL to chain call EXIT where "disk:[account]" is specified to suit your installation's needs. It need not be [1,2]. NOTE C programs will not compile if you haven't added C: as a logical device as they use this logical to locate system-wide header files. The CCL's install CC.SAV and AS.SAV to run in a 28 K-word partition. The parameter value is constructed as "8192+K" where K is the number of K-words the software is to run in. Note that these programs do not dynamically expand memory on RSTS/E. The "tools" build command files also make reference to system-wide logical PUB:. This may be assigned to [1,2] or some other "public library" account. If you do not wish to edit these files, you should add PUB: as a "system-wide logical." Make sure protection codes are set properly in the files in C:. You may also want to add CC.HLP and [6,1]CTOOLS.HLP to the help facility. Their format is compatible with the VMS help facility and must be edited for use on RSTS/E. Installing the entire system using the [5,1]RBUILD.CMD control file requires about two hours on a lightly-loaded 11/70 system. Note that RSTS/E system installation requires system manager privileges in order to install CCL commands, system wide logicals, and to create files in other accounts. No C program requires <232> privileges for its operation. If your system manager installs the RSTS/E feature patch to permit cross-account file creates within the same project and gives you a [5,0] and [6,0] account, it is possible to build Decus C without privileges. The RBUILD command file cannot be run directly, however.  C Compiler and Library Page A-11 Getting on the Air with Decus C A.5.2 Installation on VMS ____________ __ ___ This installation procedure presupposes VMS V2.0 or later. If you are running on an earlier release, you will have to edit the command files, replacing account assignments as needed. If you are running on VMS V3.0 or later, you can restore the system from magtape (VAX BACKUP format). If your Decus C distribution was in FLX format, create the various accounts and copy account [5,1] from the magtape to account [.command]: $ create/dir disk:[decusc] $ set default disk:[decusc] The VMS V2.0 file system supports relative directory access as follows: [-.subdirectory] means "move to the parent of the current directory and then down to the indicated subdirectory." This is analogous to the Unix syntax ../subdirectory This is not supported in earlier releases of VMS. If not running under VMS V2.0 or later, you will have to edit .COM files accordingly. In any case, create the following sub-directories ([P,Pn] shows the correspondance between the tape directory and disk subdirectory): [5,1] [.command] Command files and documentation [5,2] [] .DOC files [5,3] [.comp] Compiler source [5,4] [.otscom] Common (no i/o) run-time library [5,5] [.otsio] I/O run-time library [5,6] [.rstslb] RSTS/E library [5,7] [.rsxlib] RSX-11/M library [6,1] [.tools] C source for useful programs [6,2] [.misc] Various junk [6,3] [.cross] Cross-assemblers [6,4] [.lex] Lexical analyser [6,5] [.cfloat] Floating point library [6,6] [.useful] Useful subroutines [6,7] [.vaxlib] Vax native library Set [.command] as your current default and copy [5,1]VRKIT.COM from the magtape to this account: $ set default [.command] $ mount/foreign mta0:  C Compiler and Library Page A-12 Getting on the Air with Decus C $ mcr flx sy:=mt0:[5,1]vrkit.com/do Now, edit file VRKIT.COM to suit your needs and execute it. (If your distribution is on 1200 foot magtapes, you should copy VRKIT1.COM, execute it, then mount the second magtape on MTA0: and execute (after eventual editing) VRKIT2.COM. The VRKIT command procedure copies all other files to the disk. Because of the many rewinds, this command requires several hours to complete. An alternate distribution for VMS systems only uses the MCR RMSBCK utility to write each subdirectory in a "container" file. The distribution tape is labelled "C" and contains the following files: README.NOW A short file explaining the process KIT.DOC This document BCK.COM The backup command file used RST.COM A model restore command file FILEnn.BCK Container files To generate a C system from the backup tape, you must first copy RST.COM to disk, edit it to set correct disk and directory designations, then execute it as an indirect command file. After reading the kit, install the system using the VBUILD.COM command procedure. One simple way to do this is by typing the following sequence: $ set default [.command] $ @batch vbuild ! or submit vbuild This builds a temporary batch control file in your login account, submits it to batch, and sends you mail when the process completes. Batch.com requires some cooperation from your login.com file. The compiler, assembler, and run-time library are written to the parent of [.command] (generally [decusc]). The tools are written to logical BIN: which should be defined before starting the build process. (Edit vbuild.com if BIN: is not defined in your login.com file.) [.command]CCHLP.COM is a command file that adds DECUSC.HLP to the system (VMS V2.0) help library. It requires write-access to the help library. It may not be compatible with later help file conventions, nor has it been tested on later releases of VMS. Installation of VBUILD on an unloaded Vax-11/782 running VMS V3.0 takes about 90 minutes.  C Compiler and Library Page A-13 Getting on the Air with Decus C A.5.3 Installation on RSX-11M ____________ __ _______ There are command files of the format M?????.CMD. They should require no editing for RSX-11M V3.2. Execute them using the "@" system command, answering the questions as needed. Several routines in the RSX interface library are specific to the V3.2 release and will not assemble on previous releases (or on RSX-11M emulated on RSTS/E). A.5.4 Installation on RT-11 ____________ __ _____ An easy way to build an RT-11 system is to first built a RSTS/E system. Then, use ATPK to execute RTKIT.CMD (after editing) to copy files to an RT-11 format disk. To run the compiler, define logical device C: to refer to the disk containing the "#include <>" files and libraries and off you go. Command procedures of the format T?????.COM are present for "native" RT-11. They are not optimized to minimize disk storage usage. Decus C has been built on 2 RK05 RT11 systems, using one RK05 for system and one for source files. Except for "RT11.MAC", "RT11.EIS", and "RSX.MAC" (which are everywhere identical), there are no known conflicts among compiler and library file names. However, given the size of the C distribution, it would be prudent to use separate disks for the various components of the distribution. The C system runs on diskette-based systems, such as the PDT-150. (and even on a VT103 with two TU58's!) No command files are present to build the system on diskette systems. Instead, you should copy the necessary files to diskette as follows: o Build an RT-11 system containing file transfer utilities, editors, LINK.SAV, and LIBR.SAV. o Copy CC.SAV, AS.SAV, and STDIO.H to this disk (there will be only a few free blocks left). This diskette will be defined as the C: logical device. o Initialize a second diskette and copy CLIB.OBJ and SUPORT.OBJ to it. Your C programs should be created on the second disk. There will be slightly more than 300 blocks free after creating CLIB.OBJ and SUPORT.OBJ. Note that, if you omit some of the file transfer utilities, CLIB.OBJ and SUPORT.OBJ may be stored on the system disk, freeing the second diskette for your C programs. You should attempt to keep C program files quite short, using  C Compiler and Library Page A-14 Getting on the Air with Decus C the linker/librarian to build larger entities. For example, the MAZE.C program (in [6,2]) needs over 200 blocks of temporary disk storage for compilation. This is unsatisfactory in many situations. The C language system has not been tested on HT-11. Several of the library routines use RT-11 Version 3 monitor calls that are not supported on HT-11. However, it should not be too difficult to "fix" the library as needed. While all tools have been compiled using Vax-11 C, only a few have been tested in "native C." Note also that there are a few incompatiblities between Decus C and "standard" C, and several incompatibilities between the Decus run-time library and Unix-style standard libraries. A.5.5 Supporting Decus C __________ _____ _ Decus C is distributed in source format. All files are in the public-domain. WIZARD.DOC contains information on compiler data formats and library internal information. This software is made available without any support whatsoever. To support the Decus C language, run-time library, or C programs, you will need to understand and modify Macro and C source code. The authors would appreciate your communicating bug reports (with fixes!) and suggestions. The Decus "Structured Languages Special Interest Group" is the primary focus for communication among users of Decus C.  APPENDIX B LIBRARY INDEX The following is a keyword in context index to the standard library. The entry in the left-hand column is the title of the routine in the main library documentation. toascii Convert to 7-bit Ascii isascii Test for 7-bit Ascii abort trap Abort program with a BPT abs Absolute value fabs Floating absolute value qset queue Add entries to the RT11 $$fadd Floating-point add and subtract profile Print profile data after exit rtemt Execute a RT11 EMT after loading r0 $$cl16 Close all I/O channels $$flun Allocate a logical unit malloc Allocate and free memory calloc memory Allocate and initialize alloc Allocate memory $$abuf buffers Allocate memory for i/o $$falo subroutines Allocate memory for i/o sbrk operating system Allocate memory from isalloc a pointer points to allocated memory Check if $$mchk Verify memory allocation pointers isalpha Test for alphabetic argument islower Test for lower-case alphabetic argument isupper Test for upper-case alphabetic argument isalnum Test for alphanumeric argument strcat a string onto another Concatenate strncat a string onto another, with Concatenate strncpy Copy one string to another, with count $$ltoa long to Ascii (any radix) Convert $$fopt fopen/fwild options argument Scan isalpha Test for alphabetic argument isalnum Test for alphanumeric argument iscntrl for control character argument Test isdigit Test for digit argument isgraph Test for graphic argument islower lower-case alphabetic argument Test for isprint Test for printable argument  C Compiler and Library Page B-2 Library Index ispunct Test for punctuation argument isupper upper-case alphabetic argument Test for isspace Test for whitespace argument $$fcsi Parse file name argument for fopen/fwild $$dtoa floating point to ASCII Convert ddtoa floating point to ASCII -- dummy Convert atofd -- dummy Convert ASCII to floating point $$ctim $$rtim buffer to Ascii Convert $$c5ta Convert Radix-50 to Ascii r50toa Convert Radix-50 to Ascii fgetname Convert file name to Ascii itoa Convert integer to Ascii itoax to hexadecimal Ascii Convert integer itoa8 integer to octal Ascii Convert toascii Convert to 7-bit Ascii isascii Test for 7-bit Ascii $$ltoa Convert long to Ascii (any radix) ascr50 Convert Ascii to Radix-50 atod Convert Ascii to floating point atof Convert Ascii to floating point ctime Convert time value to ascii ctime time buffer to ascii asctime Convert ctime buffer to ascii asctime Convert time peek Peek at a location in RSTS/E ftime Compute time of day (augmented) ungetc Push back onto an input file $$clfu Flush last record before closing file getw file Input a binary integer from a putw Output a binary integer to a file fget Input a binary record fput Output a binary record msize Get size of a memory block zero Clear a block of memory fill character Fill a block of memory with a abort Abort program with a BPT trap localtime Build time of day buffer swabb Swap bytes in a buffer $$ctim Convert $$rtim buffer to Ascii $$utim Convert $$rtim buffer to Unix time ctime asctime Convert time buffer to ascii $$abuf memory for i/o buffers Allocate $$flsh Flush output buffers fflush Flush output buffers localtime Build time of day buffer swabi Byte swap an integer copy a given number of bytes Copy swabb Swap bytes in a buffer call subroutine from C Call (Fortran) callc subroutine from C Call (Fortran) $$main variables C library global $$main C main program csv$ environment C program execution $$init C program initialization error Error exit from C programs  C Compiler and Library Page B-3 Library Index exit Normal exit from C programs csv$ restore C register save and call subroutine from C Call (Fortran) callc subroutine from C Call (Fortran) $$qiow service Call RSX executive wrapup Dummy routine called on exit caller name of profiled caller Return calltr Trace path to the caller brk pointer Change top of memory $$cl16 Close all I/O channels ctype type table Character classification fill of memory with a character Fill a block iscntrl Test for control character argument getchar Get one character from a file index first instance of a character in a stFind the strchr first instance of a character in a stFind the inchr Find the index of a character in a string rindex last instance of a character in a stFind the strrchr last instance of a character in a stFind the putc Output one character to a file $$putc (internal) Output one character to a file $$getc Get characters (internal) isalloc points to allocated memoryck if a pointer ctype table Character classification type zero Clear a block of memory clearerr flags Clear open file's error fclear flags Clear open file's error $$main $$tick -- Clock interrupt rate $$cl16 Close all I/O channels fclose Close an open file $$clfu last record before closing file Flush exit $$exst -- Exit status code exit Exit with status code iov I/O error codes $$gcmd Parse command line msg a message on the command terminal Print strcmp Compare strings strncmp count Compare strings, with $$ctim Compute day of week strlen string Compute length of a time Compute time of day tod Compute time of day ftime (augmented) Compute time of day strcat onto another Concatenate a string strncat onto another, with countoncatenate a string concat Concatenate strings envsave and restore function context Save iscntrl argument Test for control character gettty Get control terminal name setcc mode only) Trap Control/C (RSTS/E RT11 fprintf Formatted Conversion sprintf Formatted Conversion $$tens floating point Conversion table for $$rtim Date and time conversion  C Compiler and Library Page B-4 Library Index $$scan Formatted input conversion fscanf Formatted input conversion scanf Formatted input conversion sscanf Formatted input conversion $$ctim Ascii Convert $$rtim buffer to $$utim Unix time Convert $$rtim buffer to atofd floating point -- dummyConvert ASCII to ascr50 Radix-50 Convert Ascii to atod floating point Convert Ascii to atof floating point Convert Ascii to $$c5ta Ascii Convert Radix-50 to r50toa Ascii Convert Radix-50 to fgetname Ascii Convert file name to $$dtoa to ASCII Convert floating point ddtoa to ASCII -- dummy Convert floating point itoa Convert integer to Ascii itoax hexadecimal Ascii Convert integer to itoa8 Ascii Convert integer to octal $$ltoa (any radix) Convert long to Ascii toupper upper-case Convert lower-case to atoi integer Convert string to atol Convert string to long ctime ascii asctime Convert time buffer to ctime ascii Convert time value to toascii Convert to 7-bit Ascii tolower lower-case Convert upper-case to copy bytes Copy a given number of strcpy Copy a string strncpy another, with count Copy one string to cpystr String copy strncmp Compare strings, with count strncat onto another, with countConcatenate a string strncpy to another, with count Copy one string strneq string equality, with count Test $$main $$scca -- RT-11 Ctrl/C flag profile Print profile data after exit $$rtim Date and time conversion time Compute time of day tod Compute time of day ftime Compute time of day (augmented) localtime Build time of day buffer $$ctim Compute day of week $$main $$uic -- RSX-11M default UIC $$narg Define $$narg default for RT11 startup fspool Spool file to default print queue $$narg for RT11 startup Define $$narg default iov I/O vector definition sleep of seconds Delay job a given number delete Delete a named file fmkdl Mark file for deletion kbinr read without waiting Delimiter-free terminal kbin the terminal without delimiters Read from isxdigit Test for hexadecimal digit isdigit Test for digit argument  C Compiler and Library Page B-5 Library Index div$li Long division and modulus $$div2 Unsigned division and modulus wrapup exit Dummy routine called on atofd to floating point -- dummy Convert ASCII ddtoa point to ASCII -- dummy Convert floating memdmp Dump memory or registers eis$i EIS emulator rstsys Execute a RSTS EMT rtemt Execute a RT11 EMT after loading r0 $$main $$vms -- Test if VMS emulation eis$i EIS emulator feof Test for end of file $$main $$stnd -- Stack end point qset queue Add entries to the RT11 profile $$prnl -- Profile entry per line csv$ C program execution environment streq Test strings for equality strneq Test string equality, with count error programs Error exit from C ferr Test for file error ferror Test for file error iov I/O error codes clearerr Clear open file's error flags fclear Clear open file's error flags perror Print library error message iov $$ferr -- File error value rstsys Execute a RSTS EMT rtemt loading r0 Execute a RT11 EMT after unwind Execute non-local goto setjmp longjmp -- execute non-local goto csv$ C program execution environment $$qiow Call RSX executive service exit $$exst -- Exit status code exit Exit with status code wrapup routine called on exit Dummy profile profile data after exit Print error Error exit from C programs exit Normal exit from C programs exit $$exst -- Exit status code iov $$ferr -- File error value iov $$ferr -- File error value profile -- Profile output file $$pfil fclose Close an open file delete Delete a named file $$clfu record before closing file Flush last getchar one character from a file Get getw binary integer from a file Input a fopen Open or reopen a file putw a binary integer to a file Output puts Output a string to a file putc one character to a file Output ungetc back onto an input file Push fgets Read a string from a file feof Test for end of file  C Compiler and Library Page B-6 Library Index frec if record-oriented file Test $$putc one character to a file (internal) Output ferr Test for file error ferror Test for file error fmkdl Mark file for deletion rewind Rewind a file for re-reading ftty Test if a file is a terminal isatty Test if a file is a terminal $$fcsi fopen/fwild Parse file name argument for fgetname Convert file name to Ascii $$fopa Open or reopen a file on RT11 fwild Wild-card file open fseek Reposition file pointer (seek) ftell subsequent seek Get file position for fspool queue Spool file to default print clearerr Clear open file's error flags fclear Clear open file's error flags fill with a character Fill a block of memory maxmin numbers Find maximum of two maxmin unsigned numbers Find maximum of two maxmin numbers Find minimum of two maxmin unsigned numbers Find minimum of two index of a character in a stringd the first instance strchr of a character in a stringd the first instance inchr character in a string Find the index of a rindex of a character in a stringd the last instance strrchr of a character in a stringd the last instance index character in aFind the first instance of a strchr character in aFind the first instance of a $$main -- RT-11 Ctrl/C flag $$scca clearerr open file's error flags Clear fclear open file's error flags Clear iov I/O system internal flags and vectors fabs Floating absolute value $$tens Conversion table for floating point atod Convert Ascii to floating point atof Convert Ascii to floating point atofd Convert ASCII to floating point -- dummy fps (FPS) Set floating point status $$dtoa Convert floating point to ASCII ddtoa -- dummy Convert floating point to ASCII $$fadd subtract Floating-point add and $$fmul multiply/divide Floating-point $$fsav routines Floating-point support $$clfu closing file Flush last record before $$flsh Flush output buffers fflush Flush output buffers $$fcsi name argument for fopen/fwild Parse file $$fopt argument Scan fopen/fwild options fprintf Formatted Conversion sprintf Formatted Conversion $$scan conversion Formatted input fscanf conversion Formatted input scanf conversion Formatted input  C Compiler and Library Page B-7 Library Index sscanf conversion Formatted input $$prnt Formatted output printf Formatted output call C Call (Fortran) subroutine from callc C Call (Fortran) subroutine from fps point status (FPS) Set floating malloc Allocate and free memory envsave Save and restore function context envsave Multi-level function return irand Random number generator rand Random number generator $$get Get a record (internal) $$getc (internal) Get characters gettty name Get control terminal ftell subsequent seek Get file position for fileno Get logical unit number flun Get logical unit number getchar file Get one character from a msize block Get size of a memory copy Copy a given number of bytes sleep Delay job a given number of seconds $$main C library global variables unwind Execute non-local goto setjmp -- execute non-local goto longjmp isgraph Test for graphic argument traps Operating system trap handlers itoax Convert integer to hexadecimal Ascii isxdigit Test for hexadecimal digit $$cl16 Close all I/O channels iov I/O error codes screen Screen I/O primitives iov flags and vectors I/O system internal iov I/O vector definition $$abuf Allocate memory for i/o buffers $$falo Allocate memory for i/o subroutines $$main -- Operating system id. $$opsy $$main $$pos -- Test if P/OS (Professional) $$main $$rsts -- Test if RSTS/E $$main $$vms -- Test if VMS emulation ftty Test if a file is a terminal isatty Test if a file is a terminal isalloc allocated memory Check if a pointer points to frec Test if record-oriented file wdleng Machine independent sizeof(int) inchr a string Find the index of a character in $$init C program initialization calloc Allocate and initialize memory getw from a file Input a binary integer fget Input a binary record fread Input a record $$scan Formatted input conversion fscanf Formatted input conversion scanf Formatted input conversion sscanf Formatted input conversion  C Compiler and Library Page B-8 Library Index ungetc Push back onto an input file index in a strFind the first instance of a character strchr in a strFind the first instance of a character rindex in a striFind the last instance of a character strrchr in a striFind the last instance of a character swabi Byte swap an integer atoi Convert string to integer asl$li Shift long by integer asr$u shift unsigned by integer right getw Input a binary integer from a file itoa Convert integer to Ascii putw Output a binary integer to a file itoax Ascii Convert integer to hexadecimal itoa8 Convert integer to octal Ascii iov vectors I/O system internal flags and $$get Get a record (internal) $$getc Get characters (internal) $$putc character to a file (internal) Output one $$main $$tick -- Clock interrupt rate ftty Test if a file is a terminal isatty Test if a file is a terminal sleep seconds Delay job a given number of rindex character in aFind the last instance of a strrchr character in aFind the last instance of a $$clfu closing file Flush last record before strlen Compute length of a string perror Print library error message $$main C library global variables profile -- Profile entry per line $$prnl $$gcmd Parse command line gets Read a line from stdin $$link Print memory list rtemt a RT11 EMT after loading r0 Execute peek Peek at a location in RSTS/E $$put Write a logical record $$flun Allocate a logical unit fileno Get logical unit number flun Get logical unit number div$li modulus Long division and atol Convert string to long mul$l Multiply long by long asl$l shift long by long asl$li Shift long by integer mul$l Multiply long by long asl$l shift long by long $$ltoa radix) Convert long to Ascii (any setjmp -- save state for longjmp setjmp setjmp non-local goto longjmp -- execute tolower Convert upper-case to lower-case islower argument Test for lower-case alphabetic toupper Convert lower-case to upper-case wdleng sizeof(int) Machine independent $$main C main program fmkdl Mark file for deletion  C Compiler and Library Page B-9 Library Index maxmin Find maximum of two numbers maxmin numbers Find maximum of two unsigned alloc Allocate memory malloc Allocate and free memory calloc and initialize memory Allocate isalloc points to allocated memory Check if a pointer zero Clear a block of memory realloc Reallocate memory $$mchk pointers Verify memory allocation msize Get size of a memory block $$abuf Allocate memory for i/o buffers $$falo subroutines Allocate memory for i/o sbrk system Allocate memory from operating $$link Print memory list memdmp Dump memory or registers brk Change top of memory pointer fill Fill a block of memory with a character perror Print library error message msg terminal Print a message on the command maxmin Find minimum of two numbers maxmin numbers Find minimum of two unsigned setcc (RSTS/E RT11 mode only) Trap Control/C trace Profile support module (with trace) div$li Long division and modulus $$div2 Unsigned division and modulus envsave return Multi-level function mul$l Multiply long by long $$fmul Floating-point multiply/divide $$main -- RSX-11M task name $$task gettty Get control terminal name $$fcsi fopen/fwild Parse file name argument for caller Return name of profiled caller fgetname Convert file name to Ascii delete Delete a named file $$narg startup Define $$narg default for RT11 unwind Execute non-local goto setjmp longjmp -- execute non-local goto exit programs Normal exit from C $$prmt Null prompt pointer fileno Get logical unit number flun Get logical unit number irand Random number generator rand Random number generator copy Copy a given number of bytes sleep Delay job a given number of seconds maxmin Find maximum of two numbers maxmin of two unsigned numbers Find maximum maxmin Find minimum of two numbers maxmin of two unsigned numbers Find minimum itoa8 Convert integer to octal Ascii getchar file Get one character from a putc Output one character to a file $$putc (internal) Output one character to a file strncpy with count Copy one string to another,  C Compiler and Library Page B-10 Library Index setcc (RSTS/E RT11 mode only) Trap Control/C ungetc Push back onto an input file strcat Concatenate a string onto another strncat Concatenate a string onto another, with count fopen Open or reopen a file $$fopa RT11 Open or reopen a file on fwild Wild-card file open fclose Close an open file clearerr Clear open file's error flags fclear Clear open file's error flags $$main $$opsy -- Operating system id. traps handlers Operating system trap sbrk Allocate memory from operating system $$main variables Operating-system unique $$main id. $$opsy -- Operating system $$fopt Scan fopen/fwild options argument memdmp Dump memory or registers fopen Open or reopen a file $$fopa Open or reopen a file on RT11 putw to a file Output a binary integer fput Output a binary record fwrite Output a record puts file Output a string to a putc a file Output one character to $$putc a file (internal) Output one character to $$prnt Formatted output printf Formatted output $$flsh Flush output buffers fflush Flush output buffers profile $$pfil -- Profile output file $$main $$pos -- Test if P/OS (Professional) $$gcmd Parse command line $$fcsi for fopen/fwild Parse file name argument calltr Trace path to the caller peek RSTS/E Peek at a location in profile -- Profile entry per line $$prnl profile file $$pfil -- Profile output $$main $$stnd -- Stack end point $$tens table for floating point Conversion atod Ascii to floating point Convert atof Ascii to floating point Convert atofd ASCII to floating point -- dummy Convert fps Set floating point status (FPS) $$dtoa Convert floating point to ASCII ddtoa Convert floating point to ASCII -- dummy brk Change top of memory pointer $$prmt Null prompt pointer fseek Reposition file pointer (seek) isalloc allocated meCheck if a pointer points to $$mchk memory allocation pointers Verify isalloc memoCheck if a pointer points to allocated $$main (Professional) $$pos -- Test if P/OS ftell seek Get file position for subsequent screen Screen I/O primitives  C Compiler and Library Page B-11 Library Index msg command terminal Print a message on the perror message Print library error $$link Print memory list profile exit Print profile data after fspool Spool file to default print queue isprint Test for printable argument profile per line $$prnl -- Profile entry $$main -- Test if P/OS (Professional) $$pos profile $$prnl -- Profile entry per line profile $$pfil -- Profile output file trace (with trace) Profile support module profile Print profile data after exit caller Return name of profiled caller $$main C main program csv$ environment C program execution $$init C program initialization abort Abort program with a BPT trap error Error exit from C programs exit Normal exit from C programs $$prmt Null prompt pointer ispunct Test for punctuation argument ungetc file Push back onto an input qset entries to the RT11 queue Add fspool file to default print queue Spool rtemt EMT after loading r0 Execute a RT11 $$svr1 Save registers r1-r5 on the stack $$ltoa long to Ascii (any radix) Convert ascr50 Convert Ascii to Radix-50 $$c5ta Convert Radix-50 to Ascii r50toa Convert Radix-50 to Ascii irand Random number generator rand Random number generator $$main -- Clock interrupt rate $$tick rewind Rewind a file for re-reading gets Read a line from stdin fgets file Read a string from a kbin without delimiters Read from the terminal kbinr terminal read withouDelimiter-free realloc Reallocate memory fread Input a record fget Input a binary record fwrite Output a record fput Output a binary record $$put Write a logical record $$get Get a record (internal) $$clfu file Flush last record before closing frec Test if record-oriented file csv$ restore C register save and memdmp Dump memory or registers $$svr1 stack Save registers r1-r5 on the fopen Open or reopen a file $$fopa Open or reopen a file on RT11 fseek (seek) Reposition file pointer csv$ C register save and restore  C Compiler and Library Page B-12 Library Index envsave Save and restore function context caller caller Return name of profiled envsave Multi-level function return rewind re-reading Rewind a file for asr$u integer right shift unsigned by wrapup Dummy routine called on exit $$fsav support routines Floating-point rstsys Execute a RSTS EMT $$main $$rsts -- Test if RSTS/E $$main $$rsts -- Test if RSTS/E peek Peek at a location in RSTS/E setcc Trap Control/C (RSTS/E RT11 mode only) $$qiow Call RSX executive service $$main $$uic -- RSX-11M default UIC $$main $$task -- RSX-11M task name $$main $$scca -- RT-11 Ctrl/C flag $$fopa or reopen a file on RT11 Open rtemt r0 Execute a RT11 EMT after loading setcc Control/C (RSTS/E RT11 mode only) Trap qset Add entries to the RT11 queue $$narg $$narg default for RT11 startup Define $$ctim Convert $$rtim buffer to Ascii $$utim Convert $$rtim buffer to Unix time envsave function context Save and restore $$svr1 the stack Save registers r1-r5 on csv$ C register save and restore setjmp setjmp -- save state for longjmp $$fopt argument Scan fopen/fwild options $$main flag $$scca -- RT-11 Ctrl/C screen Screen I/O primitives sleep job a given number of seconds Delay ftell for subsequent seek Get file position fseek file pointer (seek) Reposition $$qiow Call RSX executive service fps status (FPS) Set floating point setjmp longjmp setjmp -- save state for asl$li Shift long by integer asl$l shift long by long asr$u integer right shift unsigned by msize Get size of a memory block wdleng Machine independent sizeof(int) fspool print queue Spool file to default $$main $$stnd -- Stack end point $$svr1 r1-r5 on the stack Save registers $$narg default for RT11 startup Define $$narg setjmp setjmp -- save state for longjmp fps Set floating point status (FPS) exit $$exst -- Exit status code exit Exit with status code gets Read a line from stdin $$main $$stnd -- Stack end point cpystr String copy strlen Compute length of a string strcpy Copy a string  C Compiler and Library Page B-13 Library Index index of a character in a stFind the first instance strchr of a character in a stFind the first instance inchr of a character in a string Find the index rindex of a character in a strFind the last instance strrchr of a character in a strFind the last instance strneq count Test string equality, with fgets Read a string from a file strcat Concatenate a string onto another strncat with counConcatenate a string onto another, puts Output a string to a file strncpy count Copy one string to another, with atoi Convert string to integer atol Convert string to long strcmp Compare strings concat Concatenate strings streq Test strings for equality strncmp Compare strings, with count call Call (Fortran) subroutine from C callc Call (Fortran) subroutine from C $$falo memory for i/o subroutines Allocate ftell Get file position for subsequent seek $$fadd add and subtract Floating-point trace trace) Profile support module (with $$fsav Floating-point support routines swabb Swap bytes in a buffer swabi Byte swap an integer sbrk memory from operating system Allocate $$main $$opsy -- Operating system id. iov and vectors I/O system internal flags traps Operating system trap handlers ctype classification type table Character $$tens Conversion table for floating point $$main name $$task -- RSX-11M task $$main $$task -- RSX-11M task name msg on the command terminal Print a message ftty Test if a file is a terminal isatty Test if a file is a terminal gettty Get control terminal name kbinr waiting Delimiter-free terminal read without kbin delimiterRead from the terminal without isascii Test for 7-bit Ascii isalpha argument Test for alphabetic isalnum argument Test for alphanumeric iscntrl character argument Test for control isdigit Test for digit argument feof Test for end of file ferr Test for file error ferror Test for file error isgraph argument Test for graphic isxdigit digit Test for hexadecimal islower alphabetic argument Test for lower-case isprint argument Test for printable ispunct argument Test for punctuation isupper alphabetic argument Test for upper-case  C Compiler and Library Page B-14 Library Index isspace argument Test for whitespace $$main (Professional)$$pos -- Test if P/OS $$main $$rsts -- Test if RSTS/E $$main $$vms -- Test if VMS emulation ftty terminal Test if a file is a isatty terminal Test if a file is a frec file Test if record-oriented strneq with count Test string equality, streq equality Test strings for $$main rate $$tick -- Clock interrupt $$utim $$rtim buffer to Unix time Convert ctime asctime Convert time buffer to ascii $$rtim Date and time conversion time Compute time of day tod Compute time of day ftime Compute time of day (augmented) localtime Build time of day buffer ctime Convert time value to ascii brk Change top of memory pointer calltr Trace path to the caller trace support module (with trace) Profile setcc RT11 mode only) Trap Control/C (RSTS/E abort program with a BPT trap Abort traps Operating system trap handlers maxmin Find maximum of two numbers maxmin Find minimum of two numbers maxmin Find maximum of two unsigned numbers maxmin Find minimum of two unsigned numbers ctype classification type table Character $$main -- RSX-11M default UIC $$uic $$main UIC $$uic -- RSX-11M default $$main Operating-system unique variables $$flun Allocate a logical unit fileno Get logical unit number flun Get logical unit number $$utim $$rtim buffer to Unix time Convert $$div2 modulus Unsigned division and asr$u right shift unsigned by integer maxmin Find maximum of two unsigned numbers maxmin Find minimum of two unsigned numbers toupper Convert lower-case to upper-case isupper argument Test for upper-case alphabetic tolower Convert upper-case to lower-case iov $$ferr -- File error value abs Absolute value fabs Floating absolute value ctime Convert time value to ascii $$main C library global variables $$main unique variablesOperating-system iov I/O vector definition iov internal flags and vectors I/O system $$mchk pointers Verify memory allocation $$main $$vms -- Test if VMS emulation $$main emulation $$vms -- Test if VMS  C Compiler and Library Page B-15 Library Index kbinr terminal read without waiting Delimiter-free $$ctim Compute day of week isspace Test for whitespace argument kbin from the terminal without delimiters Read kbinr terminal read without waiDelimiter-free $$put Write a logical record