DECUS C LANGUAGE SYSTEM Runtime Support Library Reference Manual by Martin Minow Edited by Robert B. Denny This document describes the RSX/VMS/RSTS/RT11 DECUS C language system runtime support library. DECUS Structured Languages SIG Version of 11-Nov-83 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. 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 Runtime Support Library]] Page 2-2 Reference 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"); All information about an open file is stored in a buffer whose address is returned by fopen(). The buffer is dynamically [[ C Runtime Support Library]] Page 2-3 Reference Manual 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 Runtime Support Library]] Page 2-4 Reference Manual 2.3 Reading Data from a File _______ ____ ____ _ ____ The simplest way to read a file is to call the getchar() or getc() routines which read the next character from a file. For example, the following program counts the number of characters in a file: #include main() { register int ccount; register int lcount; register int c; FILE *ioptr; if ((ioptr = fopen("foo.bar", "r")) == NULL) error("Cannot open file"); ccount = 0; lcount = 0; while ((c = getc(ioptr)) != EOF) { ccount++; if (c == '\n') lcount++; } printf("%d characters, %d lines.\n", ccount, lcount); } Other input routines include: gets Read a line from the standard input fgets Read a line from a file fgetss Read a line from a file, remove terminator ungetc Push one character back on a file fseek Position the file to a specific record These routines are used together with the ferr() and feof() functions which allow testing for error and end of file conditions, respectively. The package assumes that all error conditions are lethal and force end of file. 2.4 Writing Data to a File _______ ____ __ _ ____ There are several routines for data output which are directly analagous to the data input routines: putchar Write a character to standard output putc Write a character to a specified file puts Write a string to the standard outpt fputs Write a string to a specified file fputss Write a record to a specified file ftell Return record location (for fseek) In addition, the printf() or fprintf() routine is used to format and print data (as was shown in the previous example). Printf() [[ C Runtime Support Library]] Page 2-5 Reference Manual is flexible, powerful, and easy to use; and is perhaps the single most important routine in the file system. 2.5 Interaction with the Operating System ___________ ____ ___ _________ ______ The support library attempts to provide a consistant operating system interface on several implementations of quite different operating systems. The possiblities include: o Native RT11 o Native RSX-11M or IAS o RT11 emulated on RSTS/E o RSX-11M emulated on RSTS/E o RSX-11M emulated on VAX/VMS This section mentions the inconsistencies and random bugs that are more or less intentionally present. 2.5.1 Logical Unit Numbers _______ ____ _______ RT11, RSTS/E, and RSX-11M use small integers to number all I/O channels. Unfortunately, the numbering is not consistent and channel usage differs among the various systems. This has resulted in several quirks: o On RT11, console terminal interaction uses the .ttyout and .print monitor functions. While no device is opened by the fopen() function, a channel number is reserved. o On RSX-11M, a channel must be allocated to the console terminal. When a C program starts, the 'command terminal' is opened on logical unit 1 and assigned to stderr. This is not done using the fopen() routine (although the stderr IOV structure is defined as if fopen() were called). Also, fclose() cannot close stderr. In addition to the standard I/O routines, there are two routines, msg() and regdmp(), that direct output to logical unit 1. These routines were used to debug the library, and are otherwise useful for disasters. On RT11, msg() and regdmp() use the .print monitor function. 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 [[ C Runtime Support Library]] Page 2-6 Reference Manual that the logical unit number of the file being closed corresponds to the proper slot in the logical unit table. o Since the standard I/O routines know little about the operating system, they do not deal with certain special features. For example, on RT11, the 'user service routine' (USR) is used to open files. The file open routine does not attempt to locate IOV areas so that the USR does not swap over them. This can be a problem for very large programs. On RSX, logical unit numbers are assigned dynamically. This means that 'LUN assignment' cannot be reliably performed by task-build control files (or task initiation). 2.5.2 Wild-Card Files _________ _____ The fwild() and fnext() routines can be used to process 'wild-card' files. On RSX-11M and VMS/RSX emulation, the file name, extension, and/or file version may be expressed as '*' to indicate wild-card support. Due to restrictions in the RSX-11 Files-11 structure (ODS1), the ' ', ';0' and ';-1' version numbers will NOT function properly on native RSX-11. This means that '*.MAC' will not work, for instance. The algorithm in fwild() depends on the directory being sorted, as in the ODS2 file structure used on VAX/VMS. If you sort the directory to be used in an fwild() operation (use the SRD program available from DECUS with the /WB switch) in order of decreasing file version numbers, then the " ", ";0", and ";-1" versions will work. Wild-card devices, units, or UIC codes are not supported. Note that, on RSX11 emulated on VMS, the ';-1' (earliest version) requires special processing by the user program, as noted in the description of fwild(). On RSX-11M emulated on RSTS/E, the file name and/or extension may contain '*' or '?' wild-cards. Wild-card devices, units, or UIC (PPN) codes are not supported. On RT-11, the file name and/or extension may contain '*', '%' or '?' wild cards. The '?' wild-card is synonymous with '%'. Wild-card devices, or units are not supported. Since wild-card 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 [[ C Runtime Support Library]] Page 2-7 Reference Manual uses a 1024 byte buffer, twice the normal size, which is shared between data and directory operations. 2.5.3 Memory allocation ______ __________ Memory is allocated using the malloc() function. It works correctly on all operating systems, expanding memory on RSX and RT11/RSTS. On 'native' RT11, all available memory is allocated by invoking the monitor .settop function with a '-2' argument. Neither library supports extended memory (PLAS) directives. The sbreak() routine may be used for permanent allocation of memory. Once memory has been allocated using sbreak(), it cannot be freed. 2.5.4 Global symbols ______ _______ Global symbols defined or referenced by C programs may cause unexpected parts of the operating-system support library to be loaded, with undesirable consequences. There are several aspects to this problem: o A symbol refered to by a C program which is not resolved by the object modules or libraries may cause some part of the system library to be loaded. For example, if a C program refers to the sqrt() function (which is not present in the standard library), the linker may attempt to load the function from the Fortran library. Since the Fortran sqrt() function contains a reference to the Fortran run-time error message routine, the load map may contain many strange global symbols. o Another problem occurs when a C program defines a global symbol that duplicates a global in the system library. This may prevent loading some necessary part of the system library, causing the link to fail with unresolved global symbols. For example, on RSX-11M emulated on RSTS/E V7.0, the following will fail: int eof; /* Global */ main () { } CHAPTER 3 LIBRARY FUNCTION DESCRIPTIONS This chapter contains descriptions of each of the C-callable runtime library functions. 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). [[ C Runtime Support Library]] Page 3-2 $$rtim .lm -16 3.1 .lm -16 ___ ___ ********** * $$rtim * ********** DIAGNOSTICS: Usage ... Illegal options cause an extensive "help" message to be printed. Bad (width | offset) ... An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-3 $$utim .lm -16 3.2 .lm -16 ___ ___ ********** * $$utim * ********** DIAGNOSTICS: Usage ... Illegal options cause an extensive "help" message to be printed. Bad (width | offset) ... An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-4 abs text file archiver 3.3 text file archiver ____ ____ ________ ******* * abs * ******* NAME: arch -- text file archiver SYNOPSIS: arch [-options] [-z logfile] archive_name file[s] DESCRIPTION: Arch manages archives (libraries) of source files, allowing a large number of small files to be stored without using excessive system resources. The following options may be specified: c Force creation of new archive d Delete file from archive. i Insert, same as update p Print files on standard output r Replace, same as update l List archive contents (directory) u Update, same as replace x Extract named files v Verbose z Write verbose log to indicated file The file name arguments may contain '*' and '?' wildcards, where '*' matches any string of characters, and '?' matches one character. ('%' may be used as a synonym for '?'.) There is a slight, but suble difference in the way wild cards are processed for the various commands: directory, delete, and extract Match ('*' and '?') against the files in the archive, performing the operation on all files that match. Except for delete, "no argument" matches all files in the archive. [[ C Runtime Support Library]] Page 3-5 abs text file archiver insert, replace, and update Expand the wild-card arguments against the files stored on the operating system -- eliminating all wild cards. Then, match against the archived files. Those that match are replaced by the file on the operating system. After replacement, any additional files are appended to the archive. Files in the archive that are not in the directory are unchanged. Currently, insert, replace, and update work the same. If it seems reasonable, the program may be extended as follows: insert Add files new only Adds new files (not present in the archive) but does not modify files currently in the archive. It would be an error to try modifying a currently archived file. replace Modify existing files only Modify files present in the archive, but do not add new files to the archive. update Modify existing, add new This is simple to do, but would seem to be a rich source of user error. NOTE: Arch has been superseded by the much simpler, but functionally identical, archi and archx programs. ARCHIVE FILE FORMAT: Archive files are standard text files. Each archive element is preceeded by a line of the format: -h- file.name date true_name Note that there is no line or byte count. To prevent problems, a '-' at the beginning of a record within a user file or embedded archive will be "quoted" by doubling it. The date and true filename fields are ignored. On Dec operating systems, file.name is forced to lowercase. DIAGNOSTICS: [[ C Runtime Support Library]] Page 3-6 abs text file archiver Diagnostic messages should be self-explanatory AUTHOR: Martin Minow BUGS: Arch used to be called ar. The name was changed to avoid conflict with the Unix tool. [[ C Runtime Support Library]] Page 3-7 cpystr $(INCLUDE) definitions. Most of the capabilities of 3.4 $(INCLUDE) definitions. Most of the capabilities of __________ ____________ ____ __ ___ ____________ __ ********** * cpystr * ********** make (and build) are unavailable. This file will probably have to be edited before it can be used. When specifing an operating system, a non-ambiguous string is required. Thus, "rstsrt11" may be abbreviated to "rstsrt". For example, note the following examples: build -l c:cu -s src: *.c >vxcubl.com build *.c -x rt11 >ttool.com The first builds the utility library for the current operating system, while the second builds tools for rt11 native mode. HEADER AND TRAILER FILE FORMAT: These files are written to the output file before (header) and after (trailer) the generated command files. They may be used to establish compilation defaults. C SOURCE FILE FORMAT: To generate the command file, build reads each source file, searching for a build command. This appears as a comment (beginning in column 1) in the C source: /*)BUILD arguments */ If a library is being built, build searches for "/*)LIBRARY". Thus libraries and programs may coexist in the same directory. Note that "/*)BUILD" or "/*)LIBRARY" must appear in upper-case at the beginning of a line. Also, the terminating "*/" must be the first non white-space characters on a line. A '#' outside of a model argument will cause the rest of the source line to be ignored, allowing comments in model strings. If no build arguments are given, the current file will be compiled. Arguments may be given to override model (or built-in) definitions. The format for an argument is as follows: [[ C Runtime Support Library]] Page 3-8 cpystr $(INCLUDE) definitions. Most of the capabilities of $X = Y where X may be either a single letter or a string enclosed in either parentheses or braces and Y may be either a single word or a string (which may contain blanks, newlines, etc.) bounded by braces. For example: /*)BUILD $(PROGRAM) = kwik $(STACK) = 2000 $(FILES) = { kwik sortc } */ Within model definitions, the '$' character may appear as itself if it is doubled "$$" or followed by a blank "$ ". The following may be specified in build arguments or model files: $(DTOA) This program requires the floating-point double-to-Ascii conversion routine. This should be written as: $(DTOA) = 1 $(DTOA) is ignored if unix or vax-native output is desired. $(ATOF) This program requires the floating-point Ascii-to-double conversion routine. This should be written as: $(ATOF) = 1 $(ATOF) is ingored if unix or vax-native output is desired. $(SRC) The account where the sources are. This overrides any -s option value. $(BIN) The account where the image goes. $(FILES) The list of files to be built. If not specified, the current file name is used. $(FILES) may be specified for programs and libraries. $(MP) To preprocess program source files by the MP macro pre-processor, define this as: $(MP) = 1 As the MP preprocessor does not have a default filetype, the build command will append ".C" to any source file that does not have an explicit filetype. This may be overridden by providing the filetype in the $(FILES) command: $(FILES) = { prog.txt } $(INCLUDE) The list of files to be included. If not [[ C Runtime Support Library]] Page 3-9 cpystr $(INCLUDE) definitions. Most of the capabilities of specified, no include files will be copied. The copy is supressed if neither $(SRC) nor $(COPYINCLUDE) have been redefined as the file would be copied from the current disk/account to itself. These files are not deleted after compilation, even if they were copied. $(INCLUDE) may be specified for programs or libraries. $(PROGRAM) The name of the program image to be generated. $(STACK) A value for the RT11 /B[OTTOM] link specifier. If not specified, "$(STACK) = 2000" will be used. Note that the RSX task-builder STACK option is specified by the $(TKBOPTIONS) specifier below. $(TKBOPTIONS) RSX task builder options (stack, units, task name, etc.) are specified by this argument as follows: $(TKBOPTIONS) = { STACK = 1500 TASK = ...FOO ; ... etc } $(OBJS) A string naming the actual object files. If specified, it overrides the default use of the files just compiled. $(LIBS) A string naming additional libraries to be searched (before searching the C runtime library). $(UTLIB) A user-specified utility library; appended to all link strings, but unspecified by BUILD. $(DECUS_LIB) On native Vax-11C, the library "C:VAXLIB/LIB" which contains interface routines for Decus-C tools. $(SUPORT) The RT11 runtime support routine: "C:SUPORT.OBJ". $(??LIB) The C runtime library: $(VXLIB) The VAX/VMS native runtime library, by default "SYS$LIBRARY:VAXCRTLIB/LIB" $(RXLIB) The RSX runtime library. The default depends on the operating system: on VAX/VMS and RSTS, it is "C:C/LB", while on native RSX-11M, it is "LB:[1,1]C/LB". $(RTLIB) The RT11 runtime library. The default is "C:SUPORT,C:CLIB". $(ODL) = {...} An RSX overlay description. If specified, a temporary file will be created (and subsequently deleted) containing a configured overlay file. Note that you should [[ C Runtime Support Library]] Page 3-10 cpystr $(INCLUDE) definitions. Most of the capabilities of reference the run-time library by using $(RXLIB) to obtain the correct library designation. If $(ODL) is specified, $(OBJS) is ignored and $(LIBS) and $(RXLIB) will be processed only if present in the $(ODL) model. For example: $(ODL) = { .ROOT MAIN1-MAIN2-$(RXLIB)-*(OV1,OV2) ; OV1: .FCTR SUB1-SUB1L SUB1L: .FCTR $(RXLIB):FWILD:FGETNA:RTIME ; OV2: .FCTR SUB2-SUB2L SUB2L: .FCTR $(RXLIB):ASL$$LI # (asl$li) ; .END } Note the use of $(RXLIB):XXX to select modules from the C library and the doubling of '$' in referencing subroutine ASL$LI. $(OVR) = {...} An RT11 overlay description. If specified, $(OBJS) is ignored. For example: $(OVR) = { root1,root2,$(SUPORT),$(RTLIB) over1/o:1 over2/o:2 } $(COMMENT) A string that will comment a command line for the target operating system. $(PREFIX) This model is expanded at the start of every compilation. The default is a comment in a format suitable for the particular operating system. $(POSTFIX) This model is expanded after every program build. On VAX/VMS, the default defines the program as an external command. On other systems, the default does nothing. $(FIRST) This model is expanded before the first program is built. By default, it does nothing. It may be defined by a user-specified model file. $(LAST) This model is expanded after the last program is built. By default, it does nothing. It may be defined by a user-specified model file. For example, /*)BUILD */ This is a "normal" build for e.g., grep or echo, signalling build that this file is a program, rather than a subroutine. /*)BUILD [[ C Runtime Support Library]] Page 3-11 cpystr $(INCLUDE) definitions. Most of the capabilities of $(PROGRAM) = xrf $(INCLUDE) = xrf.h $(FILES) = { xrf0 xrf1 xrf2 xrf3 xrfi xrfd } $(TKBOPTIONS) = { TASK = ...XRF } $(ODL) = { .ROOT XRF0-XRF2-XRFD-$(RXLIB)-*(X1,X2,X3) ; X1: .FCTR XRFI-X1L X1L: .FCTR $(RXLIB):CONCAT:CTIME:FWILD ; X2: .FCTR XRF1-X2L X2L: .FCTR $(RXLIB):ASL$$I ; X3: .FCTR XRF3-X3L X3L: .FCTR $(RXLIB):CPYSTR .END } $(OVR) = { xrf0,xrf2,xrfd,c:suport,c:clib xrfi,c:clib/o:1 xrf1,c:clib/o:1 xrf3,c:clib/o:1 } */ This slightly more complex build shows specification of an include file, the creation of a program whose name is different from its component files, task-builder options, and overlay files, including library module selection. /*)LIBRARY $(INCLUDE) = chrtab.h */ This library build file shows the naming of an include file. MODEL FILE FORMAT: Model files consist of strings of macros and their definitions. Each definition is separated by one or more blanks, tabs, or newlines. Definitions are in the same format as their )BUILD parameter counterparts. A model will (re)define defaults for the entire build. For example, the model file: $(SRC) = DK1:[6,1] # source files $(BIN) = SY:[1,3] # image output Causes all program source to be taken from DK1:[6,1] and all compiled programs to be written to SY:[1,3]. Model file definitions replace operating-system specific defaults. Anything more elaborate than redefinition of, say, $(SRC) or $(BIN), will probably require understanding of the inner logic of the build program. You should be [[ C Runtime Support Library]] Page 3-12 cpystr $(INCLUDE) definitions. Most of the capabilities of especially cautious of changing a link or library build string. BUGS: It will never replace make. It's not supposed to, anyways. The problem that build was written to solve is the extraordinary proliferation of tiny files -- each tool program requiring five or six command files: one or two for each operating system. AUTHOR: Martin Minow [[ C Runtime Support Library]] Page 3-13 fgetname .s.i -8;No : type 3.5 .s.i -8;No : type ____ _____ _ ____ ************ * fgetname * ************ A colon was followed by an unknown modifier. Class terminates badly A character class "[...]" was incorrectly terminated. For example, "[A-]" is incorrect. Unterminated class Character classes must be terminated by ']'. Class too large An internal buffer filled. Empty class A character class must designate something: "[]" is illegal. Pattern too complex An internal buffer filled. AUTHOR: David Conroy, Martin Minow. BUGS: [[ C Runtime Support Library]] Page 3-14 gets ... 3.6 ... ___ ******** * gets * ******** sort_f = "myfile.tmp"; } DIAGNOSTICS: SORTS-E-cannot create temp. file "filename" The required file cannot be created in the current directory. SORTS-E-out of main memory. The program ran out of main memory. Sorts may be optionally compiled to dump internal tables (run tables) on this error. SORTS-E-Error writing temp. file An occurred when writing the temp. file. It is probably "out of space on the disk". SORTS-F-Can't reopen temp. file SORTS-F-Empty run SORTS-F-Unexpected eof All error are fatal. "-E" errors are probably correctable by the user. "-F" errors are serious problems. If the user program defined its own comparison function, that should be checked for consistancy. AUTHOR: David Conroy, Martin Minow Revised by Bob Denny and Tim Coad BUGS: [[ C Runtime Support Library]] Page 3-15 index } */.fill.s.f:This slightly more co 3.7 } */.fill.s.f:This slightly more co _ ________________ ________ ____ __ ********* * index * ********* [[ C Runtime Support Library]] Page 3-16 msg left hand column. The kwik'ed 3.8 left hand column. The kwik'ed ____ ____ _______ ___ _______ ******* * msg * ******* [[ C Runtime Support Library]] Page 3-17 perror .s.i -8;Bad (width | offset) ... 3.9 .s.i -8;Bad (width | offset) ... ____ ______ ______ _ _______ ___ ********** * perror * ********** An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-18 printf .lm -16 3.10 .lm -16 ___ ___ ********** * printf * ********** DIAGNOSTICS: Usage ... Illegal options cause an extensive "help" message to be printed. Bad (width | offset) ... An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-19 profile .lm -16 3.11 .lm -16 ___ ___ *********** * profile * *********** DIAGNOSTICS: Usage ... Illegal options cause an extensive "help" message to be printed. Bad (width | offset) ... An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-20 putc .lm -16 3.12 .lm -16 ___ ___ ******** * putc * ******** DIAGNOSTICS: Usage ... Illegal options cause an extensive "help" message to be printed. Bad (width | offset) ... An illegal or out-of-range number was given as a parameter to a '-w' or '-t' option. Can't open exclude file Illegal exclusion An exclude file text line began with a non-printing character. The line is ignored. Out of space in saveexclude [[ C Runtime Support Library]] Page 3-21 strncat Martin Minow 3.13 Martin Minow ______ _____ *********** * strncat * *********** [[ C Runtime Support Library]] Page 3-22 strneq .nf 3.14 .nf ___ ********** * strneq * ********** .t Anything (or .t ########Anything) Getrno will change it to: .t [[Anything]] and fixdoc.c will look for same for post processing. C SOURCE FILE FORMAT: C source must have the following format: #ifdef DOCUMENTATION title tool_name header_text index index text section_head text for the section #endif Note that the comment leadin must be #ifdefDOCUMENTATION In order to define a uniform environment, getrno will insert the following commands at the beginning of the output file: .no autosubtitle .style headers 3,0,0 .pg.uc.ps 58,80.lm 8.rm 72 .hd .hd mixed .head mixed (Various flavors of runoff will flag one or more of these commands as errors, none of them fatal.) Getrno inserts the following commands between the data from each pair of files scanned: .lm 8.rm 72.nhy Within the body of the documentation, lines are handled depending on what column their text starts in (i.e. where the first non-, non- character falls); a is always assumed to put the next character at column 8. (And you thought card images were dead!) [[ C Runtime Support Library]] Page 3-23 strneq .nf An empty line becomes a .space command. Section heads begin in column 1. They will be left-justified and printed in upper case with a trailing ":". The only section heads with any special meaning to getrno are "title", "index", and "internal"; they are recognized regardless of case. "Title" and "index" must come first, as shown in the example. "Internal" flags the beginning of data that is output only if the -w switch was used; the next section head ends the "wizards only" data. However, if "internal" appears before any other section head (not counting "index"), nothing at all will be output for this file unless -w appears. Normal text starts in column 8 with a character other than a or ; it will be justified and filled, and will start in column 16 on the paper. The 's and 's that filled the first 7 columns are stripped. A line that has a or in column 8 will be output with the 's and 's that filled the first 7 columns stripped, and with runoff set to nofill mode. A line that starts with a but has a non-blank before column 8 will have the leading 's stripped and will be output with a leading ".i -8;". Lines of this form are normally used between ".lm +8"/".lm -8" pairs, as shown in the example below. A line whose first character AFTER stripping leading blanks as defined above is a "." has leading runoff commands. It is your responsibility to maintain alignment and to quote runoff-specific characters on such lines; in all other cases, getrno will do it for you. For example: diagnostics .lm +8 .s.i-8;bad file _& other stuff .s.i-8;something else .lm -8 .s author etc... Avoid manipulating fill mode directly. Getrno keeps track of whether it has set runoff to fill or nofill mode, and can get confused if you shift modes on it. Hence, the results may then not be as you expect. Note that the above example can be more easily handled as: [[ C Runtime Support Library]] Page 3-24 strneq .nf diagnostics .lm +8 bad file & other stuff something else .lm -8 author etc... MACRO SOURCE FILE FORMAT: The Macro input must have the following syntax: .title name Title line ; ;+ (Start of commentary) ; ; Index Short description for kwik index ; Index (Another short description) ; ; Usage (Start of usage information) ; ; Usage information, output, starting in column 1 ; exactly as it is written (rno .nf mode). The ; leading semicolon is not output, but the tab (or ; spaces) is. ; ; Description ; ; Description, output, starting in column 8 in ; runoff .fill mode, except that any line starting ; with ";" will be output in ; .no fill mode. The leading ";" will not be ; output. ; ; A line consisting of just ";" will generate a ; runoff .space while a line consisting of ; ";text" will generate ".indent -8 ;text". ; ;- (End of commentary) If the wizard flag (-w) is not given, a Macro source line of the format: ; Internal may be used to signal the start of package-internal information. If "Internal" preceeds "Usage", no information will be output for this file. If it follows "Usage" or "Description", text following (up to the next section initiator) will not be output. HEADER FILE FORMAT: [[ C Runtime Support Library]] Page 3-25 strneq .nf The header file is assumed to be in runoff format. It should start as follows: .comment Set top-of-form at 4 lines .comment below perforation. .ps 58,80 ! 58 lines per page, 80 columns. .lm 8 ! left margin at 8 .rm 72 ! right margin at 72 .hd Mixed ! Mixed case headings Because the left margin is set to 8, titles and subtitles should be written as: .t ########Title .st ########Subtitle The wizard flag may be used to select parts of the header file: .comment wizard *** For wizards only *** .comment else *** For non-wizards only *** .comment mundane *** Exit wizard section *** A line indicating the date on which the documentation was built, and optionally some other information, can be inserted by: .comment date[ info] The optional info will be included on the date line, which is centered. A single must appear after "date" if info appears; it is not part of info. The format of the date line is: Document compiled [info] The date inserted is in the format returned by ctime() (so it's actually the date and time). The format of all the comments is EXACTLY ".commentargument" - one space only. WORKFILE FORMAT: Each file builds one or more records (lines) in the workfile. The first has the title line, (information following .title). To allow building an index, this should be in the format: nameTitle information Following this are lines containing .rno text. The last line is followed by a record containing "!!" in the first two bytes. [[ C Runtime Support Library]] Page 3-26 strneq .nf Records with "!" in the first byte may be used to communicate information between passes: they are not written to the output. This allows writing Usage information as a separate file. Note that there is a bug in the RSTS RNO (as distributed with Version 7.0). Consequently, if your runoff source has chapter headings, you should not have explicit titles, or have page numbers. BUGS: Getrno was written to aid in documenting the Decus C libraries. (I.e., getrno and the library documentation are interdependent.) An attempt has been made to make the C-style processing generally useful; the Macro-style processing is more closely tied to the library documentation and is probably of less general interest. Further, the program, particularly in Macro mode, is very sensitive to the exact format of the input; minor variations can produce unexpected results. Some attempt has been made to avoid this in C-style processing; in Macro mode, you are on your own. Due to the size of the files involved, the usage option (-u) is no longer used in building library documentation, and is not supported in C-mode. Perhaps it should be. There should be a way to pass a "#" through to runoff within a line that is otherwise processed normally. All files are processed in the same mode. It might be useful to allow mixed-mode processing so that libraries consisting of both Macro and C modules could be handled. DIAGNOSTICS: A warning message is printed if a file does not have any documentation. There are many other messages, hopefully self-explanatory. AUTHOR: Martin Minow [[ C Runtime Support Library]] Page 3-27 ungetc .s 3.15 .s __ ********** * ungetc * ********** If no input_spec is present, the line is copied to the output with no changes other than substitution for the model string. Within a pattern, the following strings have special meaning: ? Replaced by the last model string *.* Replaced by the filename + extension * Replaced by the filename only Note that the disk and [UIC,PPN] is never output. Unflagged arguments are wild-card file specifications. For example: [[ C Runtime Support Library]] Page 3-28 wdleng diagnostics 3.16 diagnostics ___________ ********** * wdleng * ********** .lm +8 .s.i-8;bad file _& other stuff .s.i-8;something else .lm -8 .s author etc... Avoid manipulating fill mode directly. Getrno keeps track of whether it has set runoff to fill or nofill mode, and can get confused if you shift modes on it. Hence, the results may then not be as you expect. Note that the above example can be more easily handled as: diagnostics .lm +8 bad file & other stuff something else .lm -8 author etc... MACRO SOURCE FILE FORMAT: The Macro input must have the following syntax: .title name Title line ; ;+ (Start of commentary) ; ; Index Short description for kwik index ; Index (Another short description) ; ; Usage (Start of usage information) ; ; Usage information, output, starting in column 1 ; exactly as it is written (rno .nf mode). The ; leading semicolon is not output, but the tab (or ; spaces) is. ; ; Description ; ; Description, output, starting in column 8 in ; runoff .fill mode, except that any line starting ; with ";" will be output in [[ C Runtime Support Library]] Page 3-29 wdleng diagnostics ; .no fill mode. The leading ";" will not be ; output. ; ; A line consisting of just ";" will generate a ; runoff .space while a line consisting of ; ";text" will generate ".indent -8 ;text". ; ;- (End of commentary) If the wizard flag (-w) is not given, a Macro source line of the format: ; Internal may be used to signal the start of package-internal information. If "Internal" preceeds "Usage", no information will be output for this file. If it follows "Usage" or "Description", text following (up to the next section initiator) will not be output. HEADER FILE FORMAT: The header file is assumed to be in runoff format. It should start as follows: .comment Set top-of-form at 4 lines .comment below perforation. .ps 58,80 ! 58 lines per page, 80 columns. .lm 8 ! left margin at 8 .rm 72 ! right margin at 72 .hd Mixed ! Mixed case headings Because the left margin is set to 8, titles and subtitles should be written as: .t ########Title .st ########Subtitle The wizard flag may be used to select parts of the header file: .comment wizard *** For wizards only *** .comment else *** For non-wizards only *** .comment mundane *** Exit wizard section *** A line indicating the date on which the documentation was built, and optionally some other information, can be inserted by: .comment date[ info] The optional info will be included on the date line, which is centered. A single must appear after "date" if info appears; it is not part of info. The format of the date line [[ C Runtime Support Library]] Page 3-30 wdleng diagnostics is: Document compiled [info] The date inserted is in the format returned by ctime() (so it's actually the date and time). The format of all the comments is EXACTLY ".commentargument" - one space only. WORKFILE FORMAT: Each file builds one or more records (lines) in the workfile. The first has the title line, (information following .title). To allow building an index, this should be in the format: nameTitle information Following this are lines containing .rno text. The last line is followed by a record containing "!!" in the first two bytes. Records with "!" in the first byte may be used to communicate information between passes: they are not written to the output. This allows writing Usage information as a separate file. Note that there is a bug in the RSTS RNO (as distributed with Version 7.0). Consequently, if your runoff source has chapter headings, you should not have explicit titles, or have page numbers. BUGS: Getrno was written to aid in documenting the Decus C libraries. (I.e., getrno and the library documentation are interdependent.) An attempt has been made to make the C-style processing generally useful; the Macro-style processing is more closely tied to the library documentation and is probably of less general interest. Further, the program, particularly in Macro mode, is very sensitive to the exact format of the input; minor variations can produce unexpected results. Some attempt has been made to avoid this in C-style processing; in Macro mode, you are on your own. Due to the size of the files involved, the usage option (-u) is no longer used in building library documentation, and is not supported in C-mode. Perhaps it should be. There should be a way to pass a "#" through to runoff within a line that is otherwise processed normally. All files are processed in the same mode. It might be useful to allow mixed-mode processing so that libraries consisting of both Macro and C modules could be handled. [[ C Runtime Support Library]] Page 3-31 wdleng diagnostics DIAGNOSTICS: A warning message is printed if a file does not have any documentation. There are many other messages, hopefully self-explanatory. AUTHOR: Martin Minow CHAPTER 4 LIBRARY HEADER FILES This chapter contains descriptions of the standard header files that are used by C programs and libraries. These files are included in your program source by a pre-processor command of the form: #include [[ C Runtime Support Library]] Page 4-2 Reference Manual 4.1 Character test macros and global definitions _________ ____ ______ ___ ______ ___________ ********* * ctype * ********* NAME: ctype -- Character test macros and global definitions SYNOPSIS: #include DESCRIPTION: This module defines a set of character test and manipulation macros (or, on Decus C, functions) that allow classification and modification of Ascii characters. If the C compiler supports macros with arguments, the following are defined: isupper(c) /* Upper case alphabetic */ islower(c) /* Lower case alphabetic */ isalpha(c) /* Alphabetic in any case */ isdigit(c) /* Decimal digit */ isalnum(c) /* Alphabetic or digit */ isxdigit(c) /* Hexadecimal digit */ isspace(c) /* Space or tab */ ispunct(c) /* Punctuation */ isgraph(c) /* Visible character */ isprint(c) /* Printable character */ iscntrl(c) /* Control character */ isascii(c) /* 7-bit Ascii character */ _toupper(c) /* Lower case convert to Upper */ _tolower(c) /* Upper case convert to Lower */ toascii(c) /* Remove eighth (parity) bit */ Note that _toupper() and _tolower() must not be used with arguments that have side effects, such as _toupper(*ptr++); Use the functions toupper() and tolower() instead. BUGS: [[ C Runtime Support Library]] Page 4-3 fps Bit definitions for the floating point status word 4.2 Bit definitions for the floating point status word ___ ___________ ___ ___ ________ _____ ______ ____ ******* * fps * ******* NAME: fps -- Bit definitions for the floating point status word SYNOPSIS: #include DESCRIPTION: This module defines common definitions for the FP-11 floating point status word. The following are defined: FER 0100000 Floating error (sense/reset) FID 0040000 Disable all interrupts FIUV 0004000 Interrupt on undefined variable FIU 0002000 Interrupt on underflow FIV 0001000 Interrupt on overflow FIC 0000400 Interrupt on int. conv. error FD 0000200 Double precision mode FL 0000100 Long integer mode FT 0000040 Chop mode FN 0000010 Floating negative (sense) FZ 0000004 Floating zero (sense) FV 0000002 Floating overflow (sense) FC 0000001 Floating carry (sense) [[ C Runtime Support Library]] Page 4-4 initial Specify Initializers and Finalizers 4.3 Specify Initializers and Finalizers _______ ____________ ___ __________ *********** * initial * *********** NAME: initial -- Specify Initializers and Finalizers SYNOPSIS: #include INITIAL { initial-code-block }; FINAL { final-code-block }; DESCRIPTION: The macros defined in this module provide a facility for module-specific initialization and finalization code. The code in the initial-code-block is called as a normal C function before main() is called; the final-code-block is called on exit, just after wrapup(). Neither call passes any arguments. Any number of modules in an image may independently declare initializers or finalizers; all of them will be called at startup or exit. However, it is impossible to predict what order the calls will be made in, and programs should not rely on any particular ordering. A typical use of initializers and finalizers is the following: Suppose you have a package that supports access to some on-disk data base; a user of the package will call a lookup and an update function. The file containing the data base must be opened before any operations on it can take place, and it should be closed when the program is finished. (Assume that the package maintains some sort of resident buffer which it must flush.) There are two conventional approaches to solving this problem: Have the lookup and update functions check the file on each call, and open it if necessary - which could be quite expensive if they are very small functions, and in any case does not solve the problem of properly closing the file - or have the main program call an initialization and finalization function at the proper time. The problem with this latter approach is [[ C Runtime Support Library]] Page 4-5 initial Specify Initializers and Finalizers lack of modularity - the main program ought not to have to know that the module needs initialization or finalization. The solution using these macros is straightforward. The defining module includes the calls: INITIAL { open-the-data-base }; FINAL { flush-buffers-and-close-the-data-base }; The wrapup() function is treated like a built-in finalizer; however, it is guaranteed to execute before any other finalizers. (The module defining wrapup() may declare an initializer or finalizer if it wishes; it will be treated just like all other initializers and finalizers.) If any finalizer (or wrapup()) calls exit(), the program exits immediately. Notes: Using INITIAL will declare a static function named $init$(), and a (char *) named $init_; similarly, FINAL will declare $finl$() and $finl_. Also, both INITIAL and FINAL generate dsect commands. Since C provides no way to "remember" the current dsect, both macros issue a dsect "" command when they are done, restoring the C default dsect. While it is a poor idea to write code that depends on the order in which initializers and finalizers are executed, this can be useful information to have for debugging. Execution is always in the order that the modules involved were examined by the task builder or linker. When the modules are named explicitly, this will just be the order in which they were named. When the modules come from a library, it will be extremely difficult to predict the order in which they will be extracted and linked in. Warning: While initializers and finalizers provide some modularity to package initialization and finalization, they are not a panacea. For example, if package A calls routines in package B from within its initializers, and package B also declares initializers, the correct functioning of a program that includes both - hence, of any program using package A - will be problematical. BUGS: Requires the DECUS C dsect commands; hence, very non-portable. It may be possible to provide the same [[ C Runtime Support Library]] Page 4-6 initial Specify Initializers and Finalizers functionality using different techniques; if not, what's wrong with your implementation? AUTHOR: Jerry Leichter [[ C Runtime Support Library]] Page 4-7 rtime Define time buffer structure for $$rtime() 4.4 Define time buffer structure for $$rtime() ______ ____ ______ _________ ___ _________ ********* * rtime * ********* NAME: rtime -- Define time buffer structure for $$rtime() SYNOPSIS: #include ... struct TIME buffer; DESCRIPTION: This header file defines the structure of the time buffer used by the standard library $$rtime() function (which is unique to Decus C). It is defined as follows: struct TIME { int year; G.TIYR year - 1900 int month; G.TIMO Jan. = 1 int day; G.TIDA int hour; G.TIHR 00 .. 23 int minute; G.TIMI 00 .. 59 int second; G.TISC 00 .. 59 int tick; G.TICT 00 .. tsec-1 int tsec; G.TICP tick/second }; BUGS: Oboslete, use time() and localtime() instead. [[ C Runtime Support Library]] Page 4-8 setjmp Define buffer for setjump() and longjump() 4.5 Define buffer for setjump() and longjump() ______ ______ ___ _________ ___ __________ ********** * setjmp * ********** NAME: setjmp -- Define buffer for setjump() and longjump() SYNOPSIS: #include DESCRIPTION: This defines the jmp_buf array that is used for the setjmp() and longjmp() functions. BUGS: [[ C Runtime Support Library]] Page 4-9 stdio Definitions for standard i/o library 4.6 Definitions for standard i/o library ___________ ___ ________ ___ _______ ********* * stdio * ********* NAME: stdio -- Definitions for standard i/o library SYNOPSIS: #include DESCRIPTION: should be included in the assembly of all C programs that use the standard i/o library (fopen(), getc(), printf(), etc.) It defines the following: FILE The i/o routines use and return pointers to objects of this type. NULL I/O routines signal "rejection" by returning a null pointer. EOF The get character routine returns this value to signal end of file. TRUE The value 1. FALSE The value 0. EOS The "end of string" marker: '\0'. IO_SUCCESS Normal exit to operating system. IO_WARNING "Warning error" exit to operating system. IO_ERROR "Error" exit to operating system. IO_FATAL "Severe error" exit to operating system. stdin The "standard" input file. Normally the user's terminal; it may be redirected. stdout The "standard" output file. Normally the user's terminal; it may be redirected. stderr The "error" output file. It will always write [[ C Runtime Support Library]] Page 4-10 stdio Definitions for standard i/o library to the user's terminal. DIFFERENCES FROM UNIX: FILE is defined as a "typedef struc", rather than a #define. The i/o structure is considerably different from Unix. It is, however, arranged so that reasonable compatibility may be attained. Specifically, things which have the same name are used for the same purpose, and located in the same place within the I/O structure. ACCESSING THE FDB ON RSX MODES: The FDB (file data block) is the primary means of communication between the C I/O library and the RSX file control services modules. It contains file and record format information as well as pointers and counters for accessing data in the file. It is highly recommended that you do not access this information directly. Should you need to do so, the following may be done: extern char *F_RTYP; /* F.RTYP (char) in fdb */ extern char *F_SEQN; /* F.SEQN (int) in fdb */ ... fd = fopen("file.nam", "r"); /* * Set rtyp to the record type, stored as a * byte at offset F.RTYP */ rtyp = fd->io_fdb[(int) &F_RTYP] & 0377; /* * set seqn to the sequence number (printfile * fixed header), stored as an integer at * offset F.SEQN. */ seqn = *((int *) &fd->io_fdb[(int) &F_SEQN]); The somewhat messy use of casts and addressing allows the program to use the value of F.xxx stored in the RSX system library. BUGS: TRUE, FALSE, and EOS are not present in on some other C systems. If you compile with the /r switch (-r on RSX modes) or #define rsts before #include , a native RSTS/E I/O vector will be defined which is neither fully supported nor fully implemented. [[ C Runtime Support Library]] Page 4-11 time Define time buffer structure for localtime() 4.7 Define time buffer structure for localtime() ______ ____ ______ _________ ___ ___________ ******** * time * ******** NAME: time -- Define time buffer structure for localtime() SYNOPSIS: #include ... extern struct tm *localtime(); DESCRIPTION: This header file defines the structure of the time buffer used by the standard library localtime() function. It is defined as follows: struct tm { int tm_sec; /* Seconds */ int tm_min; /* Minutes */ int tm_hour; /* Hours */ int tm_mday; /* Day in month */ int tm_mon; /* Month */ int tm_year; /* Year */ int tm_wday; /* Weekday */ int tm_yday; /* Days since Jan 1 */ int tm_isdst; /* Daylight Savings = 1 */ }; extern struct tm *localtime(); BUGS: Unix V7 changed the tm_isday to tm_isdst. Thanks guys. [[ C Runtime Support Library]] Page 4-12 timeb Define timeb buffer structure for ftime() 4.8 Define timeb buffer structure for ftime() ______ _____ ______ _________ ___ _______ ********* * timeb * ********* NAME: timeb -- Define timeb buffer structure for ftime() SYNOPSIS: #include ... extern long ftime(); DESCRIPTION: This header file defines the structure of the timeb buffer used by the standard library ftime() function. It is defined as follows: struct timeb { long time; unsigned milltim; short timezone; short dstflag; }; The time value is identical to the value returned by the time() function. Milltim is the number of milliseconds in the current second. Timezone indicates the number of minutes past GMT in the current time zone (zero for Decus C) and dstflag is set if Daylight Savings Time is in effect. APPENDIX A LIBRARY INDEX The following is a keyword in context index to the standard library. The entry in the left-hand column is the title of the routine in the main library documentation. toascii Convert to 7-bit Ascii isascii Test for 7-bit Ascii abort trap Abort program with a BPT abs Absolute value fabs Floating absolute value qset queue Add entries to the RT11 profile Print profile data after exit rtemt Execute a RT11 EMT after loading r0 malloc Allocate and free memory calloc memory Allocate and initialize alloc Allocate memory sbrk operating system Allocate memory from isalloc a pointer points to allocated memory Check if $$mchk Verify memory allocation pointers isalpha Test for alphabetic argument islower Test for lower-case alphabetic argument isupper Test for upper-case alphabetic argument isalnum Test for alphanumeric argument strcat a string onto another Concatenate strncat a string onto another, with Concatenate strncpy Copy one string to another, with count isalpha Test for alphabetic argument isalnum Test for alphanumeric argument iscntrl for control character argument Test isdigit Test for digit argument isgraph Test for graphic argument islower lower-case alphabetic argument Test for isprint Test for printable argument ispunct Test for punctuation argument isupper upper-case alphabetic argument Test for isspace Test for whitespace argument $$ctim $$rtim buffer to Ascii Convert r50toa Convert Radix-50 to Ascii fgetname Convert file name to Ascii itoa Convert integer to Ascii C Compiler and Library Page A-2 Library Index itoax to hexadecimal Ascii Convert integer itoa8 integer to octal Ascii Convert toascii Convert to 7-bit Ascii isascii Test for 7-bit Ascii ascr50 Convert Ascii to Radix-50 atod Convert Ascii to floating point atof Convert Ascii to floating point ctime Convert time value to ascii ctime time buffer to ascii asctime Convert ctime buffer to ascii asctime Convert time ftime Compute time of day (augmented) ungetc Push back onto an input file getw file Input a binary integer from a putw Output a binary integer to a file fget Input a binary record fput Output a binary record msize Get size of a memory block zero Clear a block of memory fill character Fill a block of memory with a abort Abort program with a BPT trap localtime Build time of day buffer swabb Swap bytes in a buffer $$ctim Convert $$rtim buffer to Ascii $$utim Convert $$rtim buffer to Unix time ctime asctime Convert time buffer to ascii fflush Flush output buffers localtime Build time of day buffer swabi Byte swap an integer copy a given number of bytes Copy swabb Swap bytes in a buffer call subroutine from C Call (Fortran) callc subroutine from C Call (Fortran) $$main variables C library global $$main C main program csv$ environment C program execution $$init C program initialization error Error exit from C programs exit Normal exit from C programs csv$ restore C register save and call subroutine from C Call (Fortran) callc subroutine from C Call (Fortran) wrapup Dummy routine called on exit caller name of profiled caller Return calltr Trace path to the caller floor >= x ceil(x) smallest value floor Functions Floor and Ceiling Floating Point brk pointer Change top of memory ctype type table Character classification fill of memory with a character Fill a block iscntrl Test for control character argument getchar Get one character from a file index first instance of a character in a stFind the strchr first instance of a character in a stFind the inchr Find the index of a character in a string C Compiler and Library Page A-3 Library Index rindex last instance of a character in a stFind the strrchr last instance of a character in a stFind the putc Output one character to a file isalloc points to allocated memoryck if a pointer ctype table Character classification type zero Clear a block of memory clearerr flags Clear open file's error fclear flags Clear open file's error $$main $$tick -- Clock interrupt rate fclose Close an open file exit $$exst -- Exit status code exit Exit with status code iov I/O error codes $$gcmd Parse command line msg a message on the command terminal Print strcmp Compare strings strncmp count Compare strings, with $$ctim Compute day of week strlen string Compute length of a time Compute time of day tod Compute time of day ftime (augmented) Compute time of day strcat onto another Concatenate a string strncat onto another, with countoncatenate a string concat Concatenate strings envsave and restore function context Save iscntrl argument Test for control character gettty Get control terminal name setcc Trap Control/C fprintf Formatted Conversion sprintf Formatted Conversion $$rtim Date and time conversion $$scan Formatted input conversion fscanf Formatted input conversion scanf Formatted input conversion sscanf Formatted input conversion $$ctim Ascii Convert $$rtim buffer to $$utim Unix time Convert $$rtim buffer to ascr50 Radix-50 Convert Ascii to atod floating point Convert Ascii to atof floating point Convert Ascii to r50toa Ascii Convert Radix-50 to fgetname Ascii Convert file name to itoa Convert integer to Ascii itoax hexadecimal Ascii Convert integer to itoa8 Ascii Convert integer to octal toupper upper-case Convert lower-case to atoi integer Convert string to atol Convert string to long ctime ascii asctime Convert time buffer to ctime ascii Convert time value to toascii Convert to 7-bit Ascii tolower lower-case Convert upper-case to copy bytes Copy a given number of C Compiler and Library Page A-4 Library Index strcpy Copy a string strncpy another, with count Copy one string to cpystr String copy strncmp Compare strings, with count strncat onto another, with countConcatenate a string strncpy to another, with count Copy one string strneq string equality, with count Test $$main $$scca -- RT-11 Ctrl/C flag profile Print profile data after exit $$rtim Date and time conversion time Compute time of day tod Compute time of day ftime Compute time of day (augmented) localtime Build time of day buffer $$ctim Compute day of week $$main $$uic -- RSX-11M default UIC $$narg Define $$narg default for RT11 startup fspool Spool file to default print queue $$narg for RT11 startup Define $$narg default iov I/O vector definition sleep of seconds Delay job a given number delete Delete a named file fmkdl Mark file for deletion kbinr read without waiting Delimiter-free terminal kbin the terminal without delimiters Read from isxdigit Test for hexadecimal digit isdigit Test for digit argument wrapup exit Dummy routine called on memdmp Dump memory or registers rstsys Execute a RSTS EMT rtemt Execute a RT11 EMT after loading r0 $$main $$vms -- Test if VMS emulation feof Test for end of file $$main $$stnd -- Stack end point qset queue Add entries to the RT11 profile $$prnl -- Profile entry per line csv$ C program execution environment streq Test strings for equality strneq Test string equality, with count error programs Error exit from C ferr Test for file error ferror Test for file error iov I/O error codes clearerr Clear open file's error flags fclear Clear open file's error flags perror Print library error message iov $$ferr -- File error value rstsys Execute a RSTS EMT rtemt loading r0 Execute a RT11 EMT after unwind Execute non-local goto setjmp longjmp -- execute non-local goto csv$ C program execution environment exit $$exst -- Exit status code exit Exit with status code C Compiler and Library Page A-5 Library Index wrapup routine called on exit Dummy profile profile data after exit Print error Error exit from C programs exit Normal exit from C programs exit $$exst -- Exit status code iov $$ferr -- File error value iov $$ferr -- File error value profile -- Profile output file $$pfil fclose Close an open file delete Delete a named file getchar one character from a file Get getw binary integer from a file Input a fopen Open or reopen a file putw a binary integer to a file Output puts Output a string to a file putc one character to a file Output ungetc back onto an input file Push fgets Read a string from a file feof Test for end of file frec if record-oriented file Test 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 fgetname Convert file name to Ascii fwild Wild-card file open fseek Reposition file pointer (seek) ftell subsequent seek Get file position for fspool queue Spool file to default print clearerr Clear open file's error flags fclear Clear open file's error flags fill with a character Fill a block of memory maxmin numbers Find maximum of two maxmin unsigned numbers Find maximum of two maxmin numbers Find minimum of two maxmin unsigned numbers Find minimum of two index of a character in a stringd the first instance strchr of a character in a stringd the first instance inchr character in a string Find the index of a rindex of a character in a stringd the last instance strrchr of a character in a stringd the last instance index character in aFind the first instance of a strchr character in aFind the first instance of a $$main -- RT-11 Ctrl/C flag $$scca clearerr open file's error flags Clear fclear open file's error flags Clear iov I/O system internal flags and vectors floor Floor and Ceiling Floating Point Functions fabs Floating absolute value fmod Floating modulus atod Convert Ascii to floating point atof Convert Ascii to floating point C Compiler and Library Page A-6 Library Index fps (FPS) Set floating point status floor Floating Point Functionsloor and Ceiling floor <= x floor(x) largest value fflush Flush output buffers fprintf Formatted Conversion sprintf Formatted Conversion $$scan conversion Formatted input fscanf conversion Formatted input scanf conversion Formatted input sscanf conversion Formatted input $$prnt Formatted output printf Formatted output call C Call (Fortran) subroutine from callc C Call (Fortran) subroutine from fps point status (FPS) Set floating malloc Allocate and free memory envsave Save and restore function context envsave Multi-level function return floor Floating Point FunctionFloor and Ceiling irand Random number generator rand Random number generator gettty name Get control terminal ftell subsequent seek Get file position for fileno Get logical unit number flun Get logical unit number getchar file Get one character from a msize block Get size of a memory copy Copy a given number of bytes sleep Delay job a given number of seconds $$main C library global variables unwind Execute non-local goto setjmp -- execute non-local goto longjmp isgraph Test for graphic argument traps Operating system trap handlers itoax Convert integer to hexadecimal Ascii isxdigit Test for hexadecimal digit iov I/O error codes screen Screen I/O primitives iov flags and vectors I/O system internal iov I/O vector definition $$main -- Operating system id. $$opsy $$main $$pos -- Test if P/OS (Professional) $$main $$rsts -- Test if RSTS/E $$main $$vms -- Test if VMS emulation ftty Test if a file is a terminal isatty Test if a file is a terminal isalloc allocated memory Check if a pointer points to frec Test if record-oriented file wdleng Machine independent sizeof(int) inchr a string Find the index of a character in $$init C program initialization calloc Allocate and initialize memory getw from a file Input a binary integer fget Input a binary record C Compiler and Library Page A-7 Library Index fread Input a record $$scan Formatted input conversion fscanf Formatted input conversion scanf Formatted input conversion sscanf Formatted input conversion ungetc Push back onto an input file index in a strFind the first instance of a character strchr in a strFind the first instance of a character rindex in a striFind the last instance of a character strrchr in a striFind the last instance of a character swabi Byte swap an integer atoi Convert string to integer getw Input a binary integer from a file itoa Convert integer to Ascii putw Output a binary integer to a file itoax Ascii Convert integer to hexadecimal itoa8 Convert integer to octal Ascii iov vectors I/O system internal flags and $$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 floor floor(x) largest value <= x rindex character in aFind the last instance of a strrchr character in aFind the last instance of a strlen Compute length of a string perror Print library error message $$main C library global variables profile -- Profile entry per line $$prnl $$gcmd Parse command line gets Read a line from stdin $$link Print memory list rtemt a RT11 EMT after loading r0 Execute peek Peek at a location in RSTS/E fileno Get logical unit number flun Get logical unit number atol Convert string to long setjmp -- save state for longjmp setjmp setjmp non-local goto longjmp -- execute tolower Convert upper-case to lower-case islower argument Test for lower-case alphabetic toupper Convert lower-case to upper-case wdleng sizeof(int) Machine independent $$main C main program fmkdl Mark file for deletion maxmin Find maximum of two numbers maxmin numbers Find maximum of two unsigned alloc Allocate memory malloc Allocate and free memory calloc and initialize memory Allocate isalloc points to allocated memory Check if a pointer zero Clear a block of memory realloc Reallocate memory $$mchk pointers Verify memory allocation C Compiler and Library Page A-8 Library Index msize Get size of a memory block sbrk system Allocate memory from operating $$link Print memory list memdmp Dump memory or registers brk Change top of memory pointer fill Fill a block of memory with a character perror Print library error message msg terminal Print a message on the command maxmin Find minimum of two numbers maxmin numbers Find minimum of two unsigned trace Profile support module (with trace) fmod Floating modulus envsave return Multi-level function $$main -- RSX-11M task name $$task gettty Get control terminal name caller Return name of profiled caller fgetname Convert file name to Ascii delete Delete a named file $$narg startup Define $$narg default for RT11 unwind Execute non-local goto setjmp longjmp -- execute non-local goto exit programs Normal exit from C $$prmt Null prompt pointer fileno Get logical unit number flun Get logical unit number irand Random number generator rand Random number generator copy Copy a given number of bytes sleep Delay job a given number of seconds maxmin Find maximum of two numbers maxmin of two unsigned numbers Find maximum maxmin Find minimum of two numbers maxmin of two unsigned numbers Find minimum itoa8 Convert integer to octal Ascii getchar file Get one character from a putc Output one character to a file strncpy with count Copy one string to another, ungetc Push back onto an input file strcat Concatenate a string onto another strncat Concatenate a string onto another, with count fopen Open or reopen a file fwild Wild-card file open fclose Close an open file clearerr Clear open file's error flags fclear Clear open file's error flags $$main $$opsy -- Operating system id. traps handlers Operating system trap sbrk Allocate memory from operating system $$main variables Operating-system unique $$main id. $$opsy -- Operating system memdmp Dump memory or registers fopen Open or reopen a file putw to a file Output a binary integer fput Output a binary record C Compiler and Library Page A-9 Library Index fwrite Output a record puts file Output a string to a putc a file Output one character to $$prnt Formatted output printf Formatted output fflush Flush output buffers profile $$pfil -- Profile output file $$main $$pos -- Test if P/OS (Professional) $$gcmd Parse command line calltr Trace path to the caller peek RSTS/E Peek at a location in profile -- Profile entry per line $$prnl profile file $$pfil -- Profile output floor and Ceiling Floating Point Functions Floor $$main $$stnd -- Stack end point atod Ascii to floating point Convert atof Ascii to floating point Convert fps Set floating point status (FPS) brk Change top of memory pointer $$prmt Null prompt pointer fseek Reposition file pointer (seek) isalloc allocated meCheck if a pointer points to $$mchk memory allocation pointers Verify isalloc memoCheck if a pointer points to allocated $$main (Professional) $$pos -- Test if P/OS ftell seek Get file position for subsequent screen Screen I/O primitives msg command terminal Print a message on the perror message Print library error $$link Print memory list profile exit Print profile data after fspool Spool file to default print queue isprint Test for printable argument profile per line $$prnl -- Profile entry $$main -- Test if P/OS (Professional) $$pos profile $$prnl -- Profile entry per line profile $$pfil -- Profile output file trace (with trace) Profile support module profile Print profile data after exit caller Return name of profiled caller $$main C main program csv$ environment C program execution $$init C program initialization abort Abort program with a BPT trap error Error exit from C programs exit Normal exit from C programs $$prmt Null prompt pointer ispunct Test for punctuation argument ungetc file Push back onto an input qset entries to the RT11 queue Add fspool file to default print queue Spool rtemt EMT after loading r0 Execute a RT11 ascr50 Convert Ascii to Radix-50 r50toa Convert Radix-50 to Ascii C Compiler and Library Page A-10 Library Index irand Random number generator rand Random number generator $$main -- Clock interrupt rate $$tick rewind Rewind a file for re-reading gets Read a line from stdin fgets file Read a string from a kbin without delimiters Read from the terminal kbinr terminal read withouDelimiter-free realloc Reallocate memory fread Input a record fget Input a binary record fwrite Output a record fput Output a binary record frec Test if record-oriented file csv$ restore C register save and memdmp Dump memory or registers fopen Open or reopen a file 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 wrapup Dummy routine called on exit rstsys Execute a RSTS EMT $$main $$rsts -- Test if RSTS/E $$main $$rsts -- Test if RSTS/E peek Peek at a location in RSTS/E $$main $$uic -- RSX-11M default UIC $$main $$task -- RSX-11M task name $$main $$scca -- RT-11 Ctrl/C flag rtemt r0 Execute a RT11 EMT after loading qset Add entries to the RT11 queue $$narg $$narg default for RT11 startup Define $$ctim Convert $$rtim buffer to Ascii $$utim Convert $$rtim buffer to Unix time envsave function context Save and restore csv$ C register save and restore setjmp setjmp -- save state for longjmp $$main flag $$scca -- RT-11 Ctrl/C screen Screen I/O primitives sleep job a given number of seconds Delay ftell for subsequent seek Get file position fseek file pointer (seek) Reposition fps status (FPS) Set floating point setjmp longjmp setjmp -- save state for msize Get size of a memory block wdleng Machine independent sizeof(int) floor ceil(x) smallest value >= x fspool print queue Spool file to default $$main $$stnd -- Stack end point $$narg default for RT11 startup Define $$narg setjmp setjmp -- save state for longjmp fps Set floating point status (FPS) C Compiler and Library Page A-11 Library Index exit $$exst -- Exit status code exit Exit with status code gets Read a line from stdin $$main $$stnd -- Stack end point cpystr String copy strlen Compute length of a string strcpy Copy a string index of a character in a stFind the first instance strchr of a character in a stFind the first instance inchr of a character in a string Find the index rindex of a character in a strFind the last instance strrchr of a character in a strFind the last instance strneq count Test string equality, with fgets Read a string from a file strcat Concatenate a string onto another strncat with counConcatenate a string onto another, puts Output a string to a file strncpy count Copy one string to another, with atoi Convert string to integer atol Convert string to long strcmp Compare strings concat Concatenate strings streq Test strings for equality strncmp Compare strings, with count call Call (Fortran) subroutine from C callc Call (Fortran) subroutine from C ftell Get file position for subsequent seek trace trace) Profile support module (with swabb Swap bytes in a buffer swabi Byte swap an integer sbrk memory from operating system Allocate $$main $$opsy -- Operating system id. iov and vectors I/O system internal flags traps Operating system trap handlers ctype classification type table Character $$main name $$task -- RSX-11M task $$main $$task -- RSX-11M task name msg on the command terminal Print a message ftty Test if a file is a terminal isatty Test if a file is a terminal gettty Get control terminal name kbinr waiting Delimiter-free terminal read without kbin delimiterRead from the terminal without isascii Test for 7-bit Ascii isalpha argument Test for alphabetic isalnum argument Test for alphanumeric iscntrl character argument Test for control isdigit Test for digit argument feof Test for end of file ferr Test for file error ferror Test for file error isgraph argument Test for graphic isxdigit digit Test for hexadecimal islower alphabetic argument Test for lower-case C Compiler and Library Page A-12 Library Index isprint argument Test for printable ispunct argument Test for punctuation isupper alphabetic argument Test for upper-case isspace argument Test for whitespace $$main (Professional)$$pos -- Test if P/OS $$main $$rsts -- Test if RSTS/E $$main $$vms -- Test if VMS emulation ftty terminal Test if a file is a isatty terminal Test if a file is a frec file Test if record-oriented strneq with count Test string equality, streq equality Test strings for $$main rate $$tick -- Clock interrupt $$utim $$rtim buffer to Unix time Convert ctime asctime Convert time buffer to ascii $$rtim Date and time conversion time Compute time of day tod Compute time of day ftime Compute time of day (augmented) localtime Build time of day buffer ctime Convert time value to ascii brk Change top of memory pointer calltr Trace path to the caller trace support module (with trace) Profile setcc Trap Control/C abort program with a BPT trap Abort traps Operating system trap handlers maxmin Find maximum of two numbers maxmin Find minimum of two numbers maxmin Find maximum of two unsigned numbers maxmin Find minimum of two unsigned numbers ctype classification type table Character $$main -- RSX-11M default UIC $$uic $$main UIC $$uic -- RSX-11M default $$main Operating-system unique variables fileno Get logical unit number flun Get logical unit number $$utim $$rtim buffer to Unix time Convert maxmin Find maximum of two unsigned numbers maxmin Find minimum of two unsigned numbers toupper Convert lower-case to upper-case isupper argument Test for upper-case alphabetic tolower Convert upper-case to lower-case iov $$ferr -- File error value abs Absolute value fabs Floating absolute value floor floor(x) largest value <= x floor ceil(x) smallest value >= x ctime Convert time value to ascii $$main C library global variables $$main unique variablesOperating-system iov I/O vector definition iov internal flags and vectors I/O system $$mchk pointers Verify memory allocation C Compiler and Library Page A-13 Library Index $$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 from the terminal without delimiters Read kbinr terminal read without waiDelimiter-free floor smallest value >= x ceil(x)