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 avail- able. 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) C Compiler and Library Page 2-5 Software Support Manual In addition, the printf() or fprintf() routine is used to format 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 C Compiler and Library Page 2-6 Software Support Manual function. 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. C Compiler and Library Page 2-7 Software Support Manual 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 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 () { C Compiler and Library Page 2-8 Software Support Manual } 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 C Compiler and Library Page 3-2 Software Support Manual the following functions: 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 C Compiler and Library Page 3-3 Software Support Manual files are run by the ATPK system program. RSTS/E installation requires must be run from a privileged account. 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. C Compiler and Library Page 3-4 Software Support Manual 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 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. C Compiler and Library Page 3-5 Software Support Manual 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. 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. C Compiler and Library Page 3-6 Software Support Manual 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. 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, C Compiler and Library Page 3-7 Software Support Manual 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 (.STNG.) O Switch to the data P-section (.DATA.) P Switch to the program P-section (.PROG.) U Redefine program section names 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) For example, here is a simple subroutine and the intermediate code it generates: 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 C Compiler and Library Page 4-3 Software Support Manual 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 &(*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. C Compiler and Library Page 4-4 Software Support Manual 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. 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. 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 C Compiler and Library Page 4-5 Software Support Manual int any int easy [SRV] ; 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 int any int easy char any int easy [SRV] [SLAC] mov[TL] [AR], [AL] int any int any char any int any [PLA] [LR] mov[TL] [R],'(sp)+ 4.2.3 Macros used in code generation ______ ____ __ ____ __________ The following are defined in the code generator: [M] Set modulo return [F] Set function return [R] Current register [R+1] Current register + 1 [AL] Address of left [ALN] Address of left, no side effect [AR] Address of right [ARN] Address of right, no side effect [OP0] Opcode [OP1] Opcode [AL+2] Address of left, long [AR+2] Address of right, long C Compiler and Library Page 4-6 Software Support Manual [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 [SLA] Set left address [SLAC] Set left address current reg. [LL] Load left [LL+1] Load left into [R+1] [LR] Load right [PL] Push left [PLA] Push left address [PR] Push right [V] ADC or SBC for longs 4.3 Extended Hardware Support ________ ________ _______ Adding floating-point support requires writing code table entries as well as a fair amount of code to perform conversions. This is liable to be a somewhat difficult undertaking. Do not assume that any of the code that currently exists actually works correctly -- it has never been tested. 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 $$c5ta Convert Radix-50 to Ascii 5.1 Convert Radix-50 to Ascii _______ ________ __ _____ ********** * $$c5ta * ********** File name: [5,4]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-3 $$cl16 Close all channels 5.2 Close all channels _____ ___ ________ ********** * $$cl16 * ********** File name: [5,5]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-4 $$clfu Flush last record before closing 5.3 Flush last record before closing _____ ____ ______ ______ _______ ********** * $$clfu * ********** File name: [5,5]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 last buffer is fixed so it is SEE compatible. Bugs C Compiler and Library Page 5-5 $$ctim Convert $$rtim Buffer to Ascii 5.4 Convert $$rtim Buffer to Ascii _______ ______ ______ __ _____ ********** * $$ctim * ********** File name: [5,4]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-6 $$ctim Convert $$rtim Buffer to Ascii Bugs There is no range checking on the information passed. C Compiler and Library Page 5-7 $$div2 Unsigned divide (Macro only) 5.5 Unsigned divide (Macro only) ________ ______ ______ _____ ********** * $$div2 * ********** File name: [5,4]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-8 $$dtoa Convert floating to ASCII 5.6 Convert floating to ASCII _______ ________ __ _____ ********** * $$dtoa * ********** File name: [5,5]dtoa.mac Usage $$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[]. 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. $$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 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-9 $$dtoa Convert floating to ASCII 5.7 Floating-point support, add/subtract ______________ ________ ____________ ********** * $$fadd * ********** File name: [5,4]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-10 $$falo Allocate memory for i/o subroutines 5.8 Allocate memory for i/o subroutines ________ ______ ___ ___ ___________ ********** * $$falo * ********** File name: [5,5]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-11 $$fcsi Scan file name for fopen 5.9 Scan file name for fopen ____ ____ ____ ___ _____ ********** * $$fcsi * ********** File name: [5,5]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-12 $$flsh Flush output buffers 5.10 Flush output buffers _____ ______ _______ ********** * $$flsh * ********** File name: [5,5]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. Bugs C Compiler and Library Page 5-13 $$flun Allocate a logical unit for fopen 5.11 Allocate a logical unit for fopen ________ _ _______ ____ ___ _____ ********** * $$flun * ********** File name: [5,5]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-14 $$fmul Floating-point multiply/divide 5.12 Floating-point multiply/divide ______________ _______________ ********** * $$fmul * ********** File name: [5,4]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-15 $$fopa Open file (RT11 only) 5.13 Open file (RT11 only) ____ ____ _____ _____ ********** * $$fopa * ********** File name: [5,5]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-16 $$fopt Scan options parameter for fopen 5.14 Scan options parameter for fopen ____ _______ _________ ___ _____ ********** * $$fopt * ********** File name: [5,5]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-17 $$fsav Floating-point support routines 5.15 Floating-point support routines ______________ _______ ________ ********** * $$fsav * ********** File name: [5,4]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-18 $$gcmd Parse command line 5.16 Parse command line _____ _______ ____ ********** * $$gcmd * ********** File name: [5,5]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]. $$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-19 $$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 C Compiler and Library Page 5-20 $$get Get a record 5.17 Get a record ___ _ ______ ********* * $$get * ********* File name: [5,5]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 a block 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. It is fixed at 512. bytes on RT11. 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-21 $$getc Get characters 5.18 Get characters ___ __________ ********** * $$getc * ********** File name: [5,5]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. Bugs In stream files in RT11, all carriage-returns are removed. It would be more correct to remove carriage-return from or sequences. RT11 uses .ttyin to read from the user command terminal. It would be more correct to use .gtline as this would allow indirect command file tracking. C Compiler and Library Page 5-22 $$init One-time initialization code 5.19 One-time initialization code ________ ______________ ____ ********** * $$init * ********** File name: [5,5]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. 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 (argv, argc) { ... If $$narg is defined 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. Internal This module contains code that may be sensitive to particular releases of the various operating systems. Also, there may be code that is sensitive to the various types of operating system emulators. The maintainer should strive to keep all such code in this module. Diagnostics C Compiler and Library Page 5-23 $$init One-time initialization code Cannot open standard input [filename], code = nnnnnn Cannot open standard output [filename], code = nnnnnn No memory The "cannot open" messages are a user error if input or output are redirected. The associated error code is the FCS error code if the program is running under RSX, and the C library error code (described in IOV), if under RT11. The "no memory" message suggests a severe case of program immensity. All errors are fatal. Bugs On RSTS/RSX, command lines are limited to 80 bytes, although 128 byte commands are feasable. 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-24 $$ltoa Convert long to Ascii 5.20 Convert long to Ascii _______ ____ __ _____ ********** * $$ltoa * ********** File name: [5,4]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-25 $$main Start of C programs 5.21 Start of C programs _____ __ _ ________ ********** * $$main * ********** File name: [5,5]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 $$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-26 $$main Start of C programs RT11 7 $$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 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 or on RSTS/E. $$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-27 $$narg Define default for $$narg 5.22 Define default for $$narg ______ _______ ___ ______ ********** * $$narg * ********** File name: [5,4]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-28 $$put Write a record -- RSX only 5.23 Write a record -- RSX only _____ _ ______ __ ___ ____ ********* * $$put * ********* File name: [5,5]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, all registers 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. Bugs C Compiler and Library Page 5-29 $$putc Output one character to a file 5.24 Output one character to a file ______ ___ _________ __ _ ____ ********** * $$putc * ********** File name: [5,5]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. Bugs There is a bug in RS11 emulation under RSTS/E such that "*" cannot be output by the .ttyout monitor call. You should reedit the code when the bug is fixed. C Compiler and Library Page 5-30 $$qiow Call RSX executive service 5.25 Call RSX executive service ____ ___ _________ _______ ********** * $$qiow * ********** File name: [5,5]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-31 $$rtim Date and time conversion 5.26 Date and time conversion ____ ___ ____ __________ ********** * $$rtim * ********** File name: [5,5]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-32 $$svr1 Save registers r1-r5 on the stack 5.27 Save registers r1-r5 on the stack ____ _________ _____ __ ___ _____ ********** * $$svr1 * ********** File name: [5,4]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-33 $$utim Convert $$rtim buffer to Unix time 5.28 Convert $$rtim buffer to Unix time _______ ______ ______ __ ____ ____ ********** * $$utim * ********** File name: [5,5]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-34 abort Abort program with a BPT trap 5.29 Abort program with a BPT trap _____ _______ ____ _ ___ ____ ********* * abort * ********* File name: [5,5]abort.mac Usage abort() Description After closing all files, the program exits by executing a BPT trap. Bugs C Compiler and Library Page 5-35 abs Integer absolute value 5.30 Integer absolute value _______ ________ _____ ******* * abs * ******* File name: [5,4]abs.mac Usage abs(val) int val; Description Return absolute value of the integer argument. Bugs C Compiler and Library Page 5-36 alloc Allocate memory 5.31 Allocate memory ________ ______ ********* * alloc * ********* File name: [5,4]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-37 ascr50 Ascii to Radix-50 conversion 5.32 Ascii to Radix-50 conversion _____ __ ________ __________ ********** * ascr50 * ********** File name: [5,4]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-38 asl$l Shift long << long 5.33 Shift long << long _____ ____ __ ____ ********* * asl$l * ********* File name: [5,4]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-39 asl$li Shift long << integer 5.34 Shift long << integer _____ ____ __ _______ ********** * asl$li * ********** File name: [5,4]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-40 asr$u Right shift unsigned >> integer 5.35 Right shift unsigned >> integer _____ _____ ________ __ _______ ********* * asr$u * ********* File name: [5,4]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-41 atod Convert Ascii to double floating 5.36 Convert Ascii to double floating _______ _____ __ ______ ________ ******** * atod * ******** File name: [5,5]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 int, it will return a pointer to the first non-legal character.) Bugs Note: This routine uses the table in the DOUTAB module. C Compiler and Library Page 5-42 atoi Convert Ascii to integer 5.37 Convert Ascii to integer _______ _____ __ _______ ******** * atoi * ******** File name: [5,4]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-43 atol Convert Ascii to long 5.38 Convert Ascii to long _______ _____ __ ____ ******** * atol * ******** File name: [5,4]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-44 brk Change memory allocation 5.39 Change memory allocation ______ ______ __________ ******* * brk * ******* File name: [5,4]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-45 call Call (Fortran) subroutine from C 5.40 Call (Fortran) subroutine from C ____ _________ __________ ____ _ ******** * call * ******** File name: [5,4]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; C Compiler and Library Page 5-46 call Call (Fortran) subroutine from C result = call(myfun, 1, &larg); 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-47 callc Call (Fortran) subroutine from C 5.41 Call (Fortran) subroutine from C ____ _________ __________ ____ _ ********* * callc * ********* File name: [5,4]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 C Compiler and Library Page 5-48 callc Call (Fortran) subroutine from C turn, call C subroutines. 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-49 caller Return name of profiled caller 5.42 Return name of profiled caller ______ ____ __ ________ ______ ********** * caller * ********** File name: [5,4]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-50 calloc Allocate and Initialize Memory 5.43 Allocate and Initialize Memory ________ ___ __________ ______ ********** * calloc * ********** File name: [5,4]calloc.mac Usage char * calloc(n, m); /* NULL if no space */ 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-51 calltr Trace Path to the Caller 5.44 Trace Path to the Caller _____ ____ __ ___ ______ ********** * calltr * ********** File name: [5,4]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-52 clearer r Clear file error flags 5.45 r Clear file error flags _ _____ ____ _____ _____ *********** * clearer * *********** File name: [5,5]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-53 concat Concatenate strings 5.46 Concatenate strings ___________ _______ ********** * concat * ********** File name: [5,4]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-54 copy Copy a given number of bytes 5.47 Copy a given number of bytes ____ _ _____ ______ __ _____ ******** * copy * ******** File name: [5,4]copy.mac Usage char * copy(out, in, nbytes) char *out; char *in; int nbytes; 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. Bugs C Compiler and Library Page 5-55 cpystr String copy 5.48 String copy ______ ____ ********** * cpystr * ********** File name: [5,4]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-56 csv$ C register save and restore 5.49 C register save and restore _ ________ ____ ___ _______ ******** * csv$ * ******** File name: [5,4]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-57 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-58 ctime Convert time value to ascii 5.50 Convert time value to ascii _______ ____ _____ __ _____ ********* * ctime * ********* File name: [5,4]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-59 ctime Convert time value to ascii There is no range checking on the information passed. C Compiler and Library Page 5-60 ctype Character classification type table 5.51 Character classification type table _________ ______________ ____ _____ ********* * ctype * ********* File name: [5,4]ctype.mac Usage #include Description This module contains the type codes for the is... and to... routines. Bugs No provisions are made for national letters. C Compiler and Library Page 5-61 datod Convert ASCII to floating -- dummy 5.52 Convert ASCII to floating -- dummy _______ _____ __ ________ __ _____ ********* * datod * ********* File name: [5,5]atodd.mac Usage double atod(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 ascii to floating point (by calling scanf() with '%f' format effector), nothing happens! 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:atod,c:c/lb RT11: LINK file,c:atod,c:suport,c:clib/bot:2000 Bugs C Compiler and Library Page 5-62 ddtoa Convert floating to ASCII -- dummy 5.53 Convert floating to ASCII -- dummy _______ ________ __ _____ __ _____ ********* * ddtoa * ********* File name: [5,5]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-63 delete Delete a named file 5.54 Delete a named file ______ _ _____ ____ ********** * delete * ********** File name: [5,5]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 C Compiler and Library Page 5-64 div$li Long division and modulus 5.55 Long division and modulus ____ ________ ___ _______ ********** * div$li * ********** File name: [5,4]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-65 eis$i EIS emulator module 5.56 EIS emulator module ___ ________ ______ ********* * eis$i * ********* File name: [5,4]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-66 envsave Multi-level function return 5.57 Multi-level function return ___________ ________ ______ *********** * envsave * *********** File name: [5,4]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-67 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-68 error Error exit from C programs 5.58 Error exit from C programs _____ ____ ____ _ ________ ********* * error * ********* File name: [5,5]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-69 exit Exit from C programs 5.59 Exit from C programs ____ ____ _ ________ ******** * exit * ******** File name: [5,5]exit.mac Usage exit(); /* 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. Profiles (if requested) are printed. 3. All files are closed. 4. 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. Success -- no message is printed 2. 0. Warning 4. 2. Error 8. 4. Severe error Calling exit() is equivalent to calling exits(1). Note that the program may also set a value into $$exst and exit via exit(): extern int $$exst; C Compiler and Library Page 5-70 exit Exit from C programs ... $$exst = 4; exit(); If the program calls, or jumps to $$fail, it will immediately exit to the operating system without closing files, calling wrapup(), or writing a profile file. Diagnostics Bugs C Compiler and Library Page 5-71 fclear Clear file error flags 5.60 Clear file error flags _____ ____ _____ _____ ********** * fclear * ********** File name: [5,5]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-72 fclose Close a currently-open file 5.61 Close a currently-open file _____ _ ______________ ____ ********** * fclose * ********** File name: [5,5]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-73 fclose Close a currently-open file 5.62 Test for end of file ____ ___ ___ __ ____ ******** * feof * ******** File name: [5,5]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-74 ferr Test for file error 5.63 Test for file error ____ ___ ____ _____ ******** * ferr * ******** File name: [5,5]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-75 ferror Test for file error 5.64 Test for file error ____ ___ ____ _____ ********** * ferror * ********** File name: [5,5]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-76 fflush Flush output buffers 5.65 Flush output buffers _____ ______ _______ ********** * fflush * ********** File name: [5,5]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-77 fget Input a binary record 5.66 Input a binary record _____ _ ______ ______ ******** * fget * ******** File name: [5,5]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 file must have been opened using the "u" (user buffer) flag. 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. 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-78 fgetnam e Convert file name to Ascii 5.67 e Convert file name to Ascii _ _______ ____ ____ __ _____ *********** * fgetnam * *********** File name: [5,5]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. Note that fgetname() returns a fully-qualified file specification including, where possible, the disk, account, 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) FILE *fd; { register char *tp; register char c; C Compiler and Library Page 5-79 fgetnam e Convert file name to Ascii fgetname(fd, buffer); /* * Skip over device name */ for (tp = buffer; (c = *tp) && c != ':'; tp++); if (c) tp++; else tp = buffer; /* * Skip over [UIC] or * or [PPN] if present */ if (*tp == '[' || *tp == '(') { while ((c = *tp++) && c != ']' && c != ')'); if (c == 0) { error("Can't happen"); tp--; } } strcpy(buffer, tp); /* * Don't include version */ for (tp = buffer; (c = *tp) && c != ';'; tp++); *tp = 0; /* * Now, buffer has the file name, * tp - buffer, its length. */ } Bugs Various operating systems behave differently. C Compiler and Library Page 5-80 fgets Read a string from a file 5.68 Read a string from a file ____ _ ______ ____ _ ____ ********* * fgets * ********* File name: [5,5]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 file formats, such as Runoff output files or task-builder load maps, often have multiple text C Compiler and Library Page 5-81 fgets Read a string from a file lines packed into one logical record. 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-82 flun Get logical unit number 5.69 Get logical unit number ___ _______ ____ ______ ******** * flun * ******** File name: [5,5]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 C Compiler and Library Page 5-83 fmkdl Mark file for deletion -- obsolete 5.70 Mark file for deletion -- obsolete ____ ____ ___ ________ __ ________ ********* * fmkdl * ********* File name: [5,5]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. C Compiler and Library Page 5-84 fopen C library file opener 5.71 C library file opener _ _______ ____ ______ ********* * fopen * ********* File name: [5,5]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 C Compiler and Library Page 5-85 fopen C library file opener mode: 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: User does all buffering 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. The "u" flag is treated quite differently for RSX and RT11 modes. Append mode does not work on native RT11. On RSX, "u" means that the program does all I/O by calling fget() and/or fput(). Calling any other function (for example fprintf) is an error. 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 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 stored in the first two bytes of the file's block buffer. this value may be accessed from a C program (before doing any I/O) by the following sequence: FILE *fp; unsigned int file_size; ... fp = fopen("file.nam", "r"); file_size = *(unsigned *)fp->io_bbuf; Warning: the above may be changed in subsequent releases of DECUS C. C Compiler and Library Page 5-86 fopen C library file opener 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 JSW 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 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. 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 C Compiler and Library Page 5-87 fopen C library file opener $$fopn Normal open, hack append $$fopx Normal exit from fopen Warning: fopen() in RSX/RSTS mode uses unpublished 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. C Compiler and Library Page 5-88 fput Output a binary record 5.72 Output a binary record ______ _ ______ ______ ******** * fput * ******** File name: [5,5]fput.mac Usage fput(buffer, nbytes, iop); char *buffer; int nbytes; FILE *iop; Description The specified record is written to the file. The file probably should have been opened with '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-89 fread Input a record 5.73 Input a record _____ _ ______ ********* * fread * ********* File name: [5,5]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-90 frec Return True if record-oriented file 5.74 Return True if record-oriented file ______ ____ __ _______________ ____ ******** * frec * ******** File name: [5,5]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-91 fseek Reposition file pointer (seek) 5.75 Reposition file pointer (seek) __________ ____ _______ ______ ********* * fseek * ********* File name: [5,5]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 attributes. 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-92 fspool Spool file to default print queue 5.76 Spool file to default print queue _____ ____ __ _______ _____ _____ ********** * fspool * ********** File name: [5,5]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 C Compiler and Library Page 5-93 fspool Spool file to default print queue description of the spooling system function call. C Compiler and Library Page 5-94 ftell Get file position for subsequent seek 5.77 Get file position for subsequent seek ___ ____ ________ ___ __________ ____ ********* * ftell * ********* File name: [5,5]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 RSX, the value returned is the position of the file pointer (RFA), as a byte offset from the start of the file. However, on RT11, the block/byte pointers (each one word) are returned in the two word result. Returning a byte offset might be more useful, as it allows all of fseek() to be implemented. C Compiler and Library Page 5-95 ftell Get file position for subsequent seek Warning: on RSX, the above ftell/fgets sequence is valid only for "vanilla" files (such as are generated by the C I/O package. However, RSX supports many other formats, including Fortran print file and "unformatted" files (with embedded control information). The 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()). A problem arises, however, when an unformatted file is read using ftell/fgets: ftell will only return the location of the physical record -- as returned by RSX. This will not necessarily be the start of the logical record -- as returned by fgets(). The only way to handle such records is to open the file unformatted. Then, fget() is called to return each physical record and the application program deblocks logical records, recording their internal "place" within the physical record. The typeout program in the tools package, T.C, shows an example of this phenomenon. On RSTS/E RT11 mode, ftell will not process "large" files (with more than 65535 blocks) correctly. C Compiler and Library Page 5-96 ftime Compute time of day (augmented) 5.78 Compute time of day (augmented) _______ ____ __ ___ ___________ ********* * ftime * ********* File name: [5,4]ftime.mac Usage #incluee 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 timezond 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. Bugs The Unix time function returns GMT. This function returns local time. Timezone and dstflag are zero'ed. C Compiler and Library Page 5-97 ftty Test if terminal file 5.79 Test if terminal file ____ __ ________ ____ ******** * ftty * ******** File name: [5,5]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(iop) instead. C Compiler and Library Page 5-98 fwild Wild-card file open 5.80 Wild-card file open _________ ____ ____ ********* * fwild * ********* File name: [5,5]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 C Compiler and Library Page 5-99 fwild Wild-card file open reorganized (such that the youngest version appears 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. C Compiler and Library Page 5-100 fwild Wild-card file open RSX/RSTS Uses RSTS/E wildcard conventions: "*" replaces filename or filetype. "?" 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"); C Compiler and Library Page 5-101 fwild Wild-card file open The program must then test iswild to determine if it must call fnext() or if processing should be initiated directly. 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-102 fwrite Output a record 5.81 Output a record ______ _ ______ ********** * fwrite * ********** File name: [5,5]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-103 getchar Get characters 5.82 Get characters ___ __________ *********** * getchar * *********** File name: [5,5]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 after EOF, the program may execute: iop->io_flag &= ~(IO_ERR | IO_EOF); Bugs The "continue after EOF" sequence works on RT11/RSTS when reading from the terminal. It does not work on VMS compatibility mode (subsequent reads continue to give EOF). It has not been tested on other modes. C Compiler and Library Page 5-104 gets Read a string from stdin 5.83 Read a string from stdin ____ _ ______ ____ _____ ******** * gets * ******** File name: [5,5]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-105 gettty Get control terminal name 5.84 Get control terminal name ___ _______ ________ ____ ********** * gettty * ********** File name: [5,5]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-106 getw Input a binary integer from a file 5.85 Input a binary integer from a file _____ _ ______ _______ ____ _ ____ ******** * getw * ******** File name: [5,5]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-107 index Find First Instance of a Character in a String 5.86 Find First Instance of a Character in a String ____ _____ ________ __ _ _________ __ _ ______ ********* * index * ********* File name: [5,4]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 C Compiler and Library Page 5-108 iov I/O vector definition 5.87 I/O vector definition ___ ______ __________ ******* * iov * ******* File name: [5,5]iov.mac Usage RSX format: typedef struct iov { int io_flag; /* Control flags */ int io_uget; /* Unget char storage */ int io_bcnt; /* Buffer free count */ char *io_bptr; /* Buffer free pointer */ char *io_rbuf; /* Record buffer start */ int io_rbsz; /* Record buffer size */ char *io_bbuf; /* Block buffer start */ char *io_wild; /* Wildcard lookup buf */ int io_uic; /* Binary UIC (PPN) */ int io_iosb[2]; /* I/O status block */ int io_fdb[0]; /* File data block */ } FILE; RT11 format: typedef struct iov { int io_flag; /* Control flags */ int io_uget; /* Unget char storage */ char *io_name; /* File name pointer */ char *io_wild; /* Wild card lookup buf */ int io_lun; /* RT11 channel number */ int io_bcnt; /* Buffer free count */ char *io_bptr; /* Buffer free pointer */ int io_bnbr; /* Disk block number */ char io_bbuf[512]; /* Data buffer */ } FILE; Bits in iov.io_flag: #define IO_OPN 0100000 /* Open file */ #define IO_REC 0040000 /* Record device */ #define IO_TTY 0020000 /* Console terminal */ #define IO_EOF 0010000 /* EOF seen */ #define IO_ERR 0004000 /* Error seen */ #define IO_FIL 0002000 /* Disk file */ #define IO_NLH 0001000 /* No newlines hack bit */ #define IO_NOS 0000400 /* No newlines needed */ #define IO_UBF 0000200 /* User does buffering */ C Compiler and Library Page 5-109 iov I/O vector definition #define IO_BZY 0000100 /* Buffer write needed */ #define IO_WF1 0000040 /* fwild "first time" */ #define IO_VER 0000020 /* fwild version hack */ #define IO_VM1 0000010 /* version ;-1 */ #define IO_WLD 0000004 /* file is wild */ #define IO_MOD 0000003 /* Open mode mask */ /* read = 0 */ /* write = 1 */ /* append = 2 */ /* Non-zero = output */ #define IO_EOR (IO_ERR | IO_EOF) extern int $$ferr; /* Error word */ extern FILE *stdin; /* Standard input file */ extern FILE *stdout; /* Standard output file */ extern FILE *stderr; /* User's command tty */ 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 */ Description Define the I/O vector structure used for communication by all I/O routines in the C library. Note that it is slightly 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. C Compiler and Library Page 5-110 iov I/O vector definition 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 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 Error 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). Error 7 is set if fopen tries to open a channel that is already in use. 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). In RT11, buffers are managed by the C support package, functions $$putc, $$flsh, $$getc, and $$get. In these packages, the buffer control words are used as follows: If IO_BPTR equals zero, the buffer is unused. IO_BCNT will also equal zero and the get block ($$get) routine will be called to fill the first buffer, setting up all other pointers/counters. In all other cases, the following pertains: IO_BCNT Contains the number of bytes that can be inserted into the buffer before it must be written onto the disk file. IO_BPTR Contains the address of the first free location in the buffer. C Compiler and Library Page 5-111 iov I/O vector definition IO_BNBR When writing, this contains the number of the block to write when this block fills. When reading, it contains the number of the next block, which is read when this block empties. Bugs C Compiler and Library Page 5-112 irand Random number modulus argument 5.88 Random number modulus argument ______ ______ _______ ________ ********* * irand * ********* File name: [5,4]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-113 isalnum Return TRUE if Upper-case alphanumeric argument 5.89 Return TRUE if Upper-case alphanumeric argument ______ ____ __ __________ ____________ ________ *********** * isalnum * *********** File name: [5,4]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-114 isalpha Test for alphabetic argument 5.90 Test for alphabetic argument ____ ___ __________ ________ *********** * isalpha * *********** File name: [5,4]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-115 isascii Test for 7-bit Ascii character 5.91 Test for 7-bit Ascii character ____ ___ _____ _____ _________ *********** * isascii * *********** File name: [5,4]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-116 isatty Test if terminal file 5.92 Test if terminal file ____ __ ________ ____ ********** * isatty * ********** File name: [5,5]isatty.mac Usage isatty(iop) FILE *iop; Description Return 1 if the file is a terminal-type device. In general, this means the user's command terminal. Bugs C Compiler and Library Page 5-117 isctrl Test for control character argument 5.93 Test for control character argument ____ ___ _______ _________ ________ ********** * isctrl * ********** File name: [5,4]isctrl.mac Usage isctrl(c); int c; Description Return non-zero if C is a control character. Bugs C Compiler and Library Page 5-118 isdigit Return TRUE if digit argument 5.94 Return TRUE if digit argument ______ ____ __ _____ ________ *********** * isdigit * *********** File name: [5,4]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-119 isgraph Test for graphic alphabetic argument 5.95 Test for graphic alphabetic argument ____ ___ _______ __________ ________ *********** * isgraph * *********** File name: [5,4]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-120 islower Test for lower-case alphabetic argument 5.96 Test for lower-case alphabetic argument ____ ___ __________ __________ ________ *********** * islower * *********** File name: [5,4]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-121 isprint Return non-zero if printable argument 5.97 Return non-zero if printable argument ______ ________ __ _________ ________ *********** * isprint * *********** File name: [5,4]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-122 ispunct Return TRUE if punctuation argument 5.98 Return TRUE if punctuation argument ______ ____ __ ___________ ________ *********** * ispunct * *********** File name: [5,4]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-123 isspace Return non-zero if the character is "whitespace" 5.99 Return non-zero if the character is "whitespace" ______ ________ __ ___ _________ __ ____________ *********** * isspace * *********** File name: [5,4]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 not included. Bugs C Compiler and Library Page 5-124 isupper Return TRUE if Upper-case alphabetic argument 5.100 Return TRUE if Upper-case alphabetic argument ______ ____ __ __________ __________ ________ *********** * isupper * *********** File name: [5,4]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-125 isxdigi t Return non-zero if hexadecimal digit 5.101 t Return non-zero if hexadecimal digit _ ______ ________ __ ___________ _____ *********** * isxdigi * *********** File name: [5,4]isxdig.mac Usage isupper(c); int c; Description Return non-zero if C is a valid hexadecimal digit (0-9, A-F, a-f). Bugs C Compiler and Library Page 5-126 itoa Integer to Ascii 5.102 Integer to Ascii _______ __ _____ ******** * itoa * ******** File name: [5,4]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-127 itoa8 Convert integer to octal Ascii 5.103 Convert integer to octal Ascii _______ _______ __ _____ _____ ********* * itoa8 * ********* File name: [5,4]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-128 itoax Convert an integer to hexidecimal Ascii 5.104 Convert an integer to hexidecimal Ascii _______ __ _______ __ ___________ _____ ********* * itoax * ********* File name: [5,4]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-129 kbin Single Character Terminal Input 5.105 Single Character Terminal Input ______ _________ ________ _____ ******** * kbin * ******** File name: [5,5]kbin.mac Usage int kbin(); Description Read one character from the console terminal. The input character is not echoed (on RSX-11M), 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. Kbin() will strip parity from the incoming character. 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. On RSX-11M and VMS compatibility mode, 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-130 kbinr Terminal Input Without Wait 5.106 Terminal Input Without Wait ________ _____ _______ ____ ********* * kbinr * ********* File name: [5,5]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. Kbinr() will strip parity from the incoming character. 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. C Compiler and Library Page 5-131 localti me Build time of day buffer 5.107 me Build time of day buffer __ _____ ____ __ ___ ______ *********** * localti * *********** File name: [5,4]localt.mac Usage 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. C Compiler and Library Page 5-132 malloc Allocate and free memory 5.108 Allocate and free memory ________ ___ ____ ______ ********** * malloc * ********** File name: [5,4]malloc.mac Usage char * malloc(size); /* NULL if no space */ unsigned size; /* Number of bytes */ mfree(p); free(p); char *p; /* Was allocated */ Internal 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 $$link(); /* Print memory list */ Return: all 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 C Compiler and Library Page 5-133 malloc Allocate and free memory 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: 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. Note that a block need not contain any data. Free space is coalesced during the allocation search. Subroutine $$link() writes the allocation list onto stderr. It was written to debug malloc() and is conditionally compiled. Note that it preserves all registers. 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. Bugs C Compiler and Library Page 5-134 memdmp Dump memory or registers 5.109 Dump memory or registers ____ ______ __ _________ ********** * memdmp * ********** File name: [5,5]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. Note that this routine does not use the C I/O library. Bugs C Compiler and Library Page 5-135 memdmp Dump memory or registers Condition codes are not preserved. On RSX, these routines require that the terminal has been assigned as logical unit number 1. C Compiler and Library Page 5-136 msg Print a message on the command terminal 5.110 Print a message on the command terminal _____ _ _______ __ ___ _______ ________ ******* * msg * ******* File name: [5,5]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-137 mul$l Multiply long * long 5.111 Multiply long * long ________ ____ _ ____ ********* * mul$l * ********* File name: [5,4]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-138 peek Peek at a location in RSTS/E 5.112 Peek at a location in RSTS/E ____ __ _ ________ __ ______ ******** * peek * ******** File name: [5,5]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-139 perror Print Library Error Message 5.113 Print Library Error Message _____ _______ _____ _______ ********** * perror * ********** File name: [5,5]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-140 profile Print profile data 5.114 Print profile data _____ _______ ____ *********** * profile * *********** File name: [5,5]profil.mac Usage $$prof(); extern int $$prnl; extern char *$$pfil; Description $$prof is called on exit if functions have been compiled with the profile option. The profile is written to file "profil.out". This is defined by a global symbol $$pfil. 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 change the output file name: extern char *$$pfil; ... $$pfil = "ti:"; 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. Note that, by writing the data one entry per line, the C Compiler and Library Page 5-141 profile Print profile data profile output may easily be sorted either by function name or by frequency count. Bugs C Compiler and Library Page 5-142 putc Output one character to a file 5.115 Output one character to a file ______ ___ _________ __ _ ____ ******** * putc * ******** File name: [5,5]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-143 puts Output a string to a file 5.116 Output a string to a file ______ _ ______ __ _ ____ ******** * puts * ******** File name: [5,5]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-144 putw Output a binary integer to a file 5.117 Output a binary integer to a file ______ _ ______ _______ __ _ ____ ******** * putw * ******** File name: [5,5]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-145 qset Add memory to the RT11 queue area 5.118 Add memory to the RT11 queue area ___ ______ __ ___ ____ _____ ____ ******** * qset * ******** File name: [5,5]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-146 r50toa Convert Radix-50 to Ascii 5.119 Convert Radix-50 to Ascii _______ ________ __ _____ ********** * r50toa * ********** File name: [5,4]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-147 rand Random number generator 5.120 Random number generator ______ ______ _________ ******** * rand * ******** File name: [5,4]rand.mac Usage long rand() extern long seed; /* Random number seed */ Description Generate a pseudorandom number. The algorithm is: seed = (69069 * seed + 1); temp = (seed >> 8) & 32767; return ((max == 0) ? temp : temp % max); The algorithm is based on the mth$random function in the VMS common run-time library. As rand() returns a 16-bit integer, the middle of the generated random number is used. Note that the algorithm is prone to nonrandom sequences when considering the next pseudorandom number. Bugs C Compiler and Library Page 5-148 realloc Reallocate memory 5.121 Reallocate memory __________ ______ *********** * realloc * *********** File name: [5,4]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-149 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 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-150 rewind Rewind a file for re-reading 5.122 Rewind a file for re-reading ______ _ ____ ___ __________ ********** * rewind * ********** File name: [5,5]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-151 rindex Find Last Instance of a Character in a String 5.123 Find Last Instance of a Character in a String ____ ____ ________ __ _ _________ __ _ ______ ********** * rindex * ********** File name: [5,4]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 C Compiler and Library Page 5-152 salloc Allocate local memory 5.124 Allocate local memory ________ _____ ______ ********** * salloc * ********** File name: [5,4]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-153 sbrk Allocate memory from operating system 5.125 Allocate memory from operating system ________ ______ ____ _________ ______ ******** * sbrk * ******** File name: [5,5]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-154 scanf Formatted input conversion 5.126 Formatted input conversion _________ _____ __________ ********* * scanf * ********* File name: [5,4]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 */ Description Using the format string, these functions parse the input file (or given text file), storing the results in the pointer arguments. The three routines differ as follows: scanf Reads from the standard input file. fscanf Reads from the indicated file. sscanf Reads from the text buffer. The format string may contain control characters to direct the conversion of the input textual data: ' ' Blanks, tabs, or newlines match optional white space in the input stream. Use "%[ \t\n]" to match white space which is to be stored. 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. C Compiler and Library Page 5-155 scanf Formatted input conversion 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 white space 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 white space 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 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 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 C Compiler and Library Page 5-156 scanf Formatted input conversion character which is not in the set within brackets. Note that leading white space 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 No floating point -- trying it will crash the program. C Compiler and Library Page 5-157 scanf Formatted input conversion 5.127 Formatted input conversion _________ _____ __________ ********* * scanf * ********* File name: [5,5]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 */ Description Using the format string, these functions parse the input file (or given text file), storing the results in the pointer arguments. The three routines differ as follows: scanf Reads from the standard input file. fscanf Reads from the indicated file. sscanf Reads from the text buffer. The format string may contain control characters to direct the conversion of the input textual data: ' ' Blanks, tabs, or newlines are ignored in format 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. C Compiler and Library Page 5-158 scanf Formatted input conversion 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 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 C Compiler and Library Page 5-159 scanf Formatted input conversion 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-160 screen Screen I/O Primitives 5.65408 Screen I/O Primitives ______ ___ __________ ********** * screen * ********** File name: [5,5]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 */ C Compiler and Library Page 5-161 screen Screen I/O Primitives char *newbf; /* New buffer */ 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 C Compiler and Library Page 5-162 screen Screen I/O Primitives a subroutine to establish a buffer independently of its callers. Each buffer must be at least 12 bytes long. 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 C Compiler and Library Page 5-163 screen Screen I/O Primitives position to the end of the current line. (VMS Lib$Erase_Line) 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) C Compiler and Library Page 5-164 screen Screen I/O Primitives 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 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 Note: On intitialization, a VT100 will be forced into VT52 or VT100 mode depending on the determined type. Note the following normal use of scset() and scput() char **oldbuf; char mybuf[100]; main() { /* C Compiler and Library Page 5-165 screen Screen I/O Primitives * Setup */ scset(mybuf, sizeof mybuf, &oldbuf); /* * 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. 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 C Compiler and Library Page 5-166 screen Screen I/O Primitives parameters, and return error codes on being presented 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-167 setcc Trap Control/C (RSTS/E RT11 mode only) 5.65409 Trap Control/C (RSTS/E RT11 mode only) ____ _________ _______ ____ ____ _____ ********* * setcc * ********* File name: [5,5]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-168 setjmp Execute non-local goto 5.65410 Execute non-local goto _______ _________ ____ ********** * setjmp * ********** File name: [5,4]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: if (setjmp(env)) { /* Longjmp called */ } else { /* Setjmp setup called */ } The routine that called setjmp() must still be active when longjmp() is called. Bugs C Compiler and Library Page 5-169 sleep Delay job a given number of seconds 5.65411 Delay job a given number of seconds _____ ___ _ _____ ______ __ _______ ********* * sleep * ********* File name: [5,5]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. C Compiler and Library Page 5-170 sprint Formatted print routine 5.65412 Formatted print routine _________ _____ _______ ********** * sprint * ********** File name: [5,5]sprint.mac Usage printf(format, arg1, ...); char *format; char * sprintf(buffer, format, arg1, ...); fprintf(iov, format, arg1, ...); FILE *iov; char *format; (Returns a pointer to the null at the end of string.) sprintf(buffer, format, arg1, ...); char *buffer; char *format; 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. The first 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 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 C Compiler and Library Page 5-171 sprint Formatted print routine 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 the double to ascii conversion routine explicitly. The following sequences show how this is done: C Compiler and Library Page 5-172 sprint Formatted print routine 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) { error("Error at %r", &args); } C Compiler and Library Page 5-173 sprint Formatted print routine This routine might be called as follows: bug("Error %d at %s\n", val, name); 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(). 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. %r is not transportable. C Compiler and Library Page 5-174 strcat String Conctenate 5.65413 String Conctenate ______ __________ ********** * strcat * ********** File name: [5,4]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-175 strcmp String comparison 5.65414 String comparison ______ __________ ********** * strcmp * ********** File name: [5,4]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-176 strcpy String copy 5.65415 String copy ______ ____ ********** * strcpy * ********** File name: [5,4]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-177 streq String equality 5.65416 String equality ______ ________ ********* * streq * ********* File name: [5,4]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-178 strlen String length 5.65417 String length ______ ______ ********** * strlen * ********** File name: [5,4]strlen.mac Usage int strlen(s); char *s; Description Return the length of the argument string. Bugs C Compiler and Library Page 5-179 strncat String Concatenate 5.65418 String Concatenate ______ ___________ *********** * strncat * *********** File name: [5,4]strnca.mac Usage char * strncat(out, in, count); char *out; char *in; 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-180 strncmp String Compare With Count 5.65419 String Compare With Count ______ _______ ____ _____ *********** * strncmp * *********** File name: [5,4]strncm.mac Usage int strncmp(s1, s2, count); char *s1; char *s2; 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-181 strncpy String Copy With Count 5.65420 String Copy With Count ______ ____ ____ _____ *********** * strncpy * *********** File name: [5,4]strncp.mac Usage char * strncpy(out, in, count); char *out; char *in; 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-182 swabb Byte swap (argument is a buffer pointer) 5.65421 Byte swap (argument is a buffer pointer) ____ ____ _________ __ _ ______ ________ ********* * swabb * ********* File name: [5,4]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-183 swabi Byte swap, (argument is an integer) 5.65422 Byte swap, (argument is an integer) ____ _____ _________ __ __ ________ ********* * swabi * ********* File name: [5,4]swabi.mac Usage swabi(value); int value; Description Return value byte-swab'ed. Bugs C Compiler and Library Page 5-184 time Compute time of day 5.65423 Compute time of day _______ ____ __ ___ ******** * time * ******** File name: [5,5]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-185 time Compute time of day 5.65424 Convert to 7-bit Ascii _______ __ _____ _____ *********** * toascii * *********** File name: [5,4]toasci.mac Usage toascii(c); int c; Description Remove the parity bit from c. Bugs C Compiler and Library Page 5-186 tod Compute time of day 5.65425 Compute time of day _______ ____ __ ___ ******* * tod * ******* File name: [5,5]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-187 tolower Convert upper-case to lower-case 5.65426 Convert upper-case to lower-case _______ __________ __ __________ *********** * tolower * *********** File name: [5,4]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-188 toupper Convert lower-case alphabetic to upper-case 5.65427 Convert lower-case alphabetic to upper-case _______ __________ __________ __ __________ *********** * toupper * *********** File name: [5,4]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-189 trace Profile support entry module (with trace) 5.65428 Profile support entry module (with trace) _______ _______ _____ ______ _____ ______ ********* * trace * ********* File name: [5,4]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 C Compiler and Library Page 5-190 trace Profile support entry module (with trace) R5 argument pointer (for local addressing within the 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-191 traps Operating system trap handlers 5.65429 Operating system trap handlers _________ ______ ____ ________ ********* * traps * ********* File name: [5,5]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. C Compiler and Library Page 5-192 traps Operating system trap handlers Note that some errors, such as stack overflow or random 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-193 ungetc Push back a character onto an input file 5.65430 Push back a character onto an input file ____ ____ _ _________ ____ __ _____ ____ ********** * ungetc * ********** File name: [5,5]ungetc.mac Usage ungetc(c, iop); char c; FILE *iop; Description Push one character back on the indicated stream. Abort by executing a BPT instruction if more than one character is pushed back. Bugs C Compiler and Library Page 5-194 unwind Execute non-local goto 5.65431 Execute non-local goto _______ _________ ____ ********** * unwind * ********** File name: [5,4]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-195 wdleng Expensive way to say sizeof(int) 5.65432 Expensive way to say sizeof(int) _________ ___ __ ___ ___________ ********** * wdleng * ********** File name: [5,4]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-196 wrapup Dummy routine called on exit 5.65433 Dummy routine called on exit _____ _______ ______ __ ____ ********** * wrapup * ********** File name: [5,4]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-197 zero Clear a block of memory 5.65434 Clear a block of memory _____ _ _____ __ ______ ******** * zero * ******** File name: [5,4]zero.mac Usage zero(addr, nbytes); char *addr; int nbytes; Description: Clear the block of core. No value is returned. Bugs APPENDIX A 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 qset queue Add entries to the RT11 $$fadd Floating-point add and subtract profile Print profile data after exit $$cl16 Close all I/O channels $$flun Allocate a logical unit malloc Allocate and free memory calloc memory Allocate and initialize alloc Allocate memory $$falo subroutines Allocate memory for i/o sbrk operating system Allocate memory from 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 Concatenate strncpy Copy one string to another $$ltoa Convert long to Ascii (any radix) $$fopt Scan fopen/fwild options argument isalpha Test for alphabetic argument isalnum Test for alphanumeric argument isctrl 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 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 C Compiler and Library Page A-2 Library Index ddtoa floating point to ASCII -- dummy Convert datod dummy Convert ASCII to floating point -- $$ctim Convert $$rtim buffer to Ascii $$c5ta Convert Radix-50 to Ascii r50toa Convert Radix-50 to Ascii fgetname Convert file name to Ascii itoa Convert integer to Ascii itoax integer to hexadecimal Ascii Convert itoa8 Convert integer to octal Ascii 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 ctime Convert time value to ascii ctime Convert time buffer to ascii asctime ctime to ascii asctime Convert time buffer peek Peek at a location in RSTS/E doutab Internal table for ATOD and DTOA routines ftime Compute time of day (augmented) ungetc Push back onto an input file $$clfu Flush last record before closing file getw Input a binary integer from a file putw Output a binary integer to a file fget Input a binary record fput Output a binary record zero Clear a block of memory 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 $$flsh Flush output buffers fflush Flush output buffers localtime Build time of day buffer swabi Byte swap an integer copy Copy a given number of bytes swabb Swap bytes in a buffer call subroutine from C Call (Fortran) callc subroutine from C Call (Fortran) $$main C library global variables $$main C main program csv$ environment C program execution $$init C program initialization error Error exit from C programs exit Normal exit from C programs csv$ C register save and restore call from C Call (Fortran) subroutine callc from C Call (Fortran) subroutine $$qiow Call RSX executive service wrapup Dummy routine called on exit caller Return name of profiled caller C Compiler and Library Page A-3 Library Index calltr Trace path to the caller brk pointer Change top of memory $$cl16 Close all I/O channels ctype type table Character classification isctrl Test for control character argument getchar Get one character from a file index the first instance of a character in a string Find rindex the last instance of a character in a string Find putc Output one character to a file $$putc (internal) Output one character to a file $$getc Get characters (internal) ctype Character classification type table 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 Flush last record before closing file exit $$exst -- Exit status code exit Exit with status code iov I/O error codes $$gcmd Parse command line msg Print a message on the command terminal streq equality Compare strings for strncmp Compare two strings strcmp String comparison $$ctim Compute day of week strlen Compute length of a string time Compute time of day tod Compute time of day ftime (augmented) Compute time of day strcat another Concatenate a string onto strncat another Concatenate a string onto concat Concatenate strings envsave and restore function context Save isctrl Test for control character argument gettty Get control terminal name setcc only) Trap Control/C (RSTS/E RT11 mode $$rtim Date and time conversion scanf Formatted input conversion scanf Formatted input conversion $$ctim Ascii Convert $$rtim buffer to $$utim Unix time Convert $$rtim buffer to datod point -- dummy Convert ASCII to floating ascr50 Convert Ascii to Radix-50 atod point Convert Ascii to floating $$c5ta Convert Radix-50 to Ascii r50toa Convert Radix-50 to Ascii fgetname Convert file name to Ascii $$dtoa ASCII Convert floating point to ddtoa ASCII -- dummy Convert floating point to itoa Convert integer to Ascii C Compiler and Library Page A-4 Library Index itoax hexadecimal Ascii Convert integer to itoa8 Ascii Convert integer to octal $$ltoa radix) Convert long to Ascii (any toupper upper-case Convert lower-case to atoi Convert string to integer atol Convert string to long ctime ascii asctime Convert time buffer to ctime Convert time value to ascii 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 Copy one string to another cpystr String copy $$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 RT11 startup Define $$narg default for iov I/O vector definition sleep seconds Delay job a given number of 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 div$li Long division and modulus $$div2 Unsigned division and modulus doutab table for ATOD and DTOA routines Internal wrapup exit Dummy routine called on datod to floating point -- dummy Convert ASCII ddtoa point to ASCII -- dummy Convert floating memdmp Dump memory or registers eis$i EIS emulator $$main $$vms -- Test if VMS emulation eis$i EIS emulator feof Test for end of file $$main $$stnd -- Stack end point qset Add entries to the RT11 queue profile $$prnl -- Profile entry per line csv$ C program execution environment streq Compare strings for equality error Error exit from C programs ferr Test for file error ferror Test for file error C Compiler and Library Page A-5 Library Index 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 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 Dummy routine called on exit profile Print profile data after exit 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 $$pfil -- Profile output file fclose Close an open file delete Delete a named file $$clfu record before closing file Flush last getchar Get one character from a file getw a binary integer from a file Input 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 Push back onto an input file fgets Read a string from a file feof Test for end of file frec Test if record-oriented file $$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 Spool file to default print queue clearerr Clear open file's error flags fclear Clear open file's error flags index a character in a string Find the first instance of rindex character in a string Find the last instance of a index character in a stFind the first instance of a $$main $$scca -- RT-11 Ctrl/C flag clearerr Clear open file's error flags C Compiler and Library Page A-6 Library Index fclear Clear open file's error flags iov I/O system internal flags and vectors atod Convert Ascii to floating point datod Convert ASCII to floating point -- dummy $$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 file name argument for fopen/fwild Parse $$fopt argument Scan fopen/fwild options scanf Formatted input conversion scanf Formatted input conversion sprint Formatted output call Call (Fortran) subroutine from C callc Call (Fortran) subroutine from C 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 Get characters (internal) gettty Get control terminal name ftell subsequent seek Get file position for flun Get logical unit number getchar file Get one character from a 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 and vectors I/O system internal flags iov I/O vector definition $$falo Allocate memory for i/o subroutines $$main -- Operating system id. $$opsy $$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 frec Test if record-oriented file wdleng Machine independent sizeof(int) $$init C program initialization C Compiler and Library Page A-7 Library Index calloc Allocate and initialize memory getw a file Input a binary integer from fget Input a binary record fread Input a record scanf Formatted input conversion scanf Formatted input conversion ungetc Push back onto an input file index a string Find the first instance of a character in rindex a string Find the last instance of a character in swabi Byte swap an integer atoi Convert string to integer asl$li Shift long by integer asr$u right shift unsigned by integer 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 doutab DTOA routines Internal table for ATOD and iov I/O system internal flags and vectors $$get Get a record (internal) $$getc Get characters (internal) $$putc one character to a file (internal) Output $$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 a stFind the last instance of a $$clfu file Flush last record before closing 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 peek Peek at a location in RSTS/E $$put Write a logical record $$flun Allocate a logical unit flun Get logical unit number div$li Long division and modulus 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 Convert long to Ascii (any radix) setjmp setjmp -- save state for longjmp 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 C Compiler and Library Page A-8 Library Index $$main C main program fmkdl Mark file for deletion alloc Allocate memory malloc Allocate and free memory calloc Allocate and initialize memory zero Clear a block of memory realloc Reallocate memory $$falo Allocate memory for i/o subroutines sbrk system Allocate memory from operating memdmp Dump memory or registers brk Change top of memory pointer perror Print library error message msg terminal Print a message on the command setcc Control/C (RSTS/E RT11 mode only) Trap trace Profile support module (with trace) div$li Long division and modulus $$div2 Unsigned division and modulus envsave Multi-level function return mul$l Multiply long by long $$fmul Floating-point multiply/divide $$main $$task -- RSX-11M task name 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 Normal exit from C programs 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 itoa8 Convert integer to octal Ascii getchar Get one character from a file putc Output one character to a file $$putc (internal) Output one character to a file strncpy Copy one string to another 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 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 C Compiler and Library Page A-9 Library Index $$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 a file Output a binary integer to fput Output a binary record fwrite Output a record puts Output a string to a file putc file Output one character to a $$putc file (internal) Output one character to a sprint Formatted output $$flsh Flush output buffers fflush Flush output buffers profile $$pfil -- Profile output file $$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 $$prnl -- Profile entry per line profile $$pfil -- Profile output file $$main $$stnd -- Stack end point atod Ascii to floating point Convert datod ASCII to floating point -- dummy Convert $$dtoa Convert floating point to ASCII ddtoa Convert floating point to ASCII -- dummy brk Change top of memory pointer fseek Reposition file pointer (seek) ftell seek Get file position for subsequent screen Screen I/O primitives msg command terminal Print a message on the perror Print library error message profile exit Print profile data after fspool Spool file to default print queue isprint Test for printable argument profile line $$prnl -- Profile entry per 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 ispunct Test for punctuation argument ungetc file Push back onto an input qset Add entries to the RT11 queue fspool file to default print queue Spool $$svr1 Save registers r1-r5 on the stack C Compiler and Library Page A-10 Library Index $$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 Read a string from a file kbin without delimiters Read from the terminal kbinr Delimiter-free terminal read without waiting 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 Flush last record before closing file frec Test if record-oriented file csv$ C register save and restore 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 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 Floating-point support routines doutab table for ATOD and DTOA routines Internal $$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 Open or reopen a file on RT11 setcc Trap Control/C (RSTS/E RT11 mode only) 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 context Save and restore function $$svr1 stack Save registers r1-r5 on the csv$ C register save and restore C Compiler and Library Page A-11 Library Index setjmp setjmp -- save state for longjmp $$fopt argument Scan fopen/fwild options $$main $$scca -- RT-11 Ctrl/C flag screen Screen I/O primitives sleep job a given number of seconds Delay ftell position for subsequent seek Get file fseek Reposition file pointer (seek) $$qiow Call RSX executive service setjmp longjmp setjmp -- save state for asl$li Shift long by integer asl$l shift long by long asr$u right shift unsigned by integer wdleng Machine independent sizeof(int) fspool queue Spool file to default print $$main $$stnd -- Stack end point $$svr1 registers r1-r5 on the stack Save $$narg $$narg default for RT11 startup Define setjmp setjmp -- save state for longjmp exit $$exst -- Exit status code exit Exit with status code gets Read a line from stdin $$main $$stnd -- Stack end point strcmp String comparison cpystr String copy strlen Compute length of a string strcpy Copy a string index of a character in a strinFind the first instance rindex of a character in a stringFind the last instance fgets Read a string from a file strcat Concatenate a string onto another strncat Concatenate a string onto another puts Output a string to a file strncpy Copy one string to another atoi Convert string to integer atol Convert string to long strncmp Compare two strings concat Concatenate strings streq Compare strings for equality call Call (Fortran) subroutine from C callc Call (Fortran) subroutine from C $$falo Allocate memory for i/o subroutines ftell Get file position for subsequent seek $$fadd Floating-point add and subtract trace Profile support module (with trace) $$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 vectors I/O system internal flags and traps Operating system trap handlers ctype classification type table Character doutab routines Internal table for ATOD and DTOA C Compiler and Library Page A-12 Library Index $$main $$task -- RSX-11M task name $$main $$task -- RSX-11M task name msg a message on the command terminal Print 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 Read from the terminal without delimiters isascii Test for 7-bit Ascii isalpha argument Test for alphabetic isalnum argument Test for alphanumeric isctrl argument Test for control character isdigit Test for digit argument feof Test for end of file ferr Test for file error ferror Test for file error isgraph Test for graphic argument isxdigit Test for hexadecimal digit islower alphabetic argument Test for lower-case isprint Test for printable argument ispunct argument Test for punctuation isupper alphabetic argument Test for upper-case isspace argument Test for whitespace $$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 $$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 mode only) Trap Control/C (RSTS/E RT11 abort Abort program with a BPT trap traps Operating system trap handlers strncmp Compare two strings ctype Character classification type table $$main $$uic -- RSX-11M default UIC $$main $$uic -- RSX-11M default UIC $$main Operating-system unique variables $$flun Allocate a logical unit flun Get logical unit number $$utim Convert $$rtim buffer to Unix time $$div2 modulus Unsigned division and asr$u right shift unsigned by integer C Compiler and Library Page A-13 Library Index 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 ctime Convert time value to ascii $$main C library global variables $$main Operating-system unique variables iov I/O vector definition iov internal flags and vectors I/O system $$main $$vms -- Test if VMS emulation $$main emulation $$vms -- Test if VMS kbinr terminal read without waiting Delimiter-free $$ctim Compute day of week isspace Test for whitespace argument fwild Wild-card file open kbin Read from the terminal without delimiters kbinr terminal read without waitinDelimiter-free $$put Write a logical record