.TOC .TTL DECUS C LANGUAGE SYSTEM Runtime Support Library Reference Manual by Martin Minow Edited by Robert B. Denny .INT This document describes the RSX/VMS/RSTS/RT11 DECUS C language system runtime support library. .LIN 4 .MID DECUS Structured Languages SIG .LIN .MID Version of 7-Aug-80 .LIN .MID Copyright (C) 1980, DECUS .PAG General permission to copy or modify, but not for profit, is hereby granted, provided that the above copyright notice is included and reference made to the fact that reproduction privileges were granted by DECUS. .BLN The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation or by DECUS. .BLN Neither Digital Equipment Corporation, DECUS, nor the authors assume any responsibility for the use or reliability of this document or the described software. .BLN 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. .LIN 7 UNIX is a trademark of Bell Telephone Laboratories. RSX, RSTS/E, RT11 and VMS are trademarks of Digital Equipment Corporation. .CPT Introduction .LIN The C support library contains three major groups of functions: .AND Functions called by the compiler to perform certain mathematical operations (such as floating-point multiply or function entrance) that are not performed in-line. .AND 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. .AND An implementation of (most of) the Unix Standard I/O library. .LIN The standard installation procedure yields two documents: CLIB.DOC, containing normal user documentation and WIZARD.DOC, containing information on all library routines, even those which are not directly called by user programs. This is CLIB.DOC. .CPT The Standard Library .LIN The RSX standard run-time library is in C:C.OLB. The RT11 standard run-time library is in C:CLIB.OBJ. .LIN 2 .MID WARNING .BLN This version of the library is somewhat incompatible with previous versions of the Decus C compiler and with Unix Version 6. This incompatibility allows greater compatibility with Unix Version 7. .BLN The standard I/O interface header file is in C:STDIO.H and should be included in all C programs as follows: .SWT 1 #include .LIN .HLV 1 Introduction to Unix-style Stream I/O .BLN 0 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: .AND Opening and closing files .AND 0 Reading data from files .AND 0 Writing data to files .LIN 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. .BLN When a C program is started, three files are predefined and opened: .SWT stdin The `standard' input file stdout The `standard' output file stderr The `standard' error file .BLN 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. .HLV 1 Opening and Closing Files .LIN The fopen and fclose functions control access to files. They are normally used as follows: .SWT #include /* Define standard I/O */ FILE *ioptr; /* Pointer to file area */ ... if ((ioptr = fopen("filename", "mode")) == NULL) error("Can't open file"); .LIN 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: .SWT r Read only w Write new file a Append to existing file (or write new) (Doesn't work on RT11 modes). .BLN It also defines some record-control information: .SWT n No newlines mode (`binary' files) u RSX: The user program allocates record buffers RT11: Console output is done using .ttyout .BLN 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. .BLN 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.) .BLN 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: .BLN .MID if (freopen("tt:", "wu", stdout) == NULL) error(""); .LIN 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. .CPT Reading Data from a File .LIN 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: .SWT #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) { count++; if (c == '\n') lcount++; } printf("%d characters, %d lines.\n", ccount, lcount); } .LIN Other input routines include: .SWT 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 .LIN 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. .HLV 1 Writing Data to a File .LIN There are several routines for data output which are directly analagous to the data input routines: .SWT 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) .LIN 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. .HLV 1 Interaction with the Operating System .LIN The support library attempts to provide a consistant operating system interface on several implementations of quite different operating systems. The possiblities include: .SWT o Native RT11 o Native RSX11-M or IAS o RT11 emulated on RSTS/E o RSX11-M emulated on RSTS/E o RSX11-M emulated on VAX/VMS .BLN This section mentions the inconsistencies and random bugs that are more or less intentionally present. .HLV 2 Logical Unit Numbers - .LIN RT11, RSTS/E, and RSX11-M 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: .AND On RT11, console terminal interaction uses the .ttyout and .print monitor functions. While no device is opened by the fopen() function, an channel number is reserved. .AND On RSX11-M, 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. .LIN 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. Note that, on RT11, msg() and regdmp() use the .print monitor function. .AND 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. .AND Since the standard I/O routines know little about the operating system, they do not deal with certain special features. .BLN 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). .HLV 2 Wild-Card Files - .LIN On native RSX11-M and RSX11-M emulated on VMS or RSTS/E, the fwild() and fnext() routines can be used to process `wild-card' files. This functionality is not (currently) supported on RT11 modes. .BLN On RSX11-M and VMS/RSX emulation, the file name, extension, and/or file version may be expressed as `*' to indicate wild-card support. Also, fwild() properly handles version numbers `;0' and `;-1'. 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(). .BLN On RSX11-M 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. .HLV 2 Memory allocation - .LIN 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. .BLN The sbreak() routine may be used for permanent allocation of memory. Once memory has been allocated using sbreak(), it cannot be freed. .HLV 3 $$init Once-only initialization code .SWT Usage .SWT Description .BLN 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: .BLN 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. .BLN On RT11, if no command line is passed to the program, it will prompt "Argv:" and read a line from the command terminal. To disable this, the user program must define a global flag as follows: .SWT $$narg = 1; main (argv, argc) { ... .BLN If $$narg is defined non-zero and no command line is passed to the program, main() will be called with one (dummy) argument. .SWT 2 Diagnostics 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 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 stderr cannot be initialized or partition parameters obtained. .HLV 3 $$init Once-only initialization code .SWT Usage $$main:: /* Start of C programs */ extern int $$opsy; /* Operating system */ extern int $$rsts; /* Non-zero if RSTS/E */ 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; /* RT11: 50 or 60 Hertz */ .SWT Description .BLN 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. .BLN The following globals are defined in this module: .SWT $$opsy Operating system unique value. This value is 7 on RT11, and set as per the GTSK$ directive on RSX-based systems. $$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. $$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 On RT11, the clock interrupt rate. This will equal either 50 or 60. $$uic On RSX, the default UIC word from GTSK$. Diagnostics .BLN On RSX, the task aborts with a BPT if the standard error file did not open. Otherwise, explanatory error messages are printed. .SWT Bugs .HLV 3 $$main Start of C programs .SWT Usage int $$narg = ; ... main() { ... } .SWT Description .BLN On native RT11, if no command line is provided when the program starts, it prints "Argv:" on the command terminal, reads one line, and builds the argv[] array. If this is undesirable, include a global definition of $$narg in a C program as follows: .BLN .MID int $$narg = 1; .BLN This will supress the command terminal read operation. The argv[] vector will be set to a dummy value. .BLN If the user program does not define $$narg, it will be defined so as to enable the "Argv:" prompt. .BLN Note that $$narg must be initilized at compilation time. It is tested by the initialization code before the main() program is called. .SWT Bugs .HLV 3 abort Abort program with an IOT trap .SWT Usage abort() .SWT Description .BLN After closing all files, the program exits by executing a BPT trap. .SWT Bugs .HLV 3 abs Integer absolute value .SWT Usage abs(val) int val; .SWT Description .BLN Return absolute value of the integer argument. .SWT Bugs .HLV 3 alloc Allocate memory .SWT Usage char * alloc(n); /* -1 if no space */ .SWT Description .BLN Allocate the requested number of bytes, returning a pointer to the first. The program image will be expanded as needed. .BLN alloc() returns -1 if the requested space could not be allocated. .BLN free() is used to return the buffer to free space. .BLN See also the description of malloc(), realloc() and sbreak(). .SWT Diagnostics Bugs alloc() is obsolete. Use malloc() for new programs. .HLV 3 ascr50 Ascii to Radix-50 conversion .SWT Usage ascr50(count, input, output) int count; int *output; char *input; .SWT Description .BLN 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. .SWT Bugs .HLV 3 asr$u Right shift unsigned >> integer .SWT Usage unsigned asr$u(u, n) unsigned u; int n; .SWT Description .BLN Performs u >> n for unsigneds. Note that, if n is negative, it acts as if (u << (-n)) were executed. .SWT Bugs .HLV 3 atod Convert Ascii to double floating .SWT Usage double atod(buffer) char *buffer; .SWT Description .BLN Convert the argument string to a double-precision floating point binary number. The conversion stops on the first non-legal character. The caller is assumed to have already checked the argument for legality. .SWT Bugs Not quite written yet (as there is no compiler fpu support). .HLV 3 atoi Convert Ascii to integer .SWT Usage atoi(p) char *p; .SWT Description .BLN 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. .SWT Bugs .HLV 3 atol Convert Ascii to long .SWT Usage long atol(p) char *p; .SWT Description .BLN 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. .SWT Bugs .HLV 3 break Change memory allocation .SWT Usage char * old = sbrk(increment); int *old; int increment; char * old = brk(value); int *old; int *value; char * new = settop(value); int *value; int *new; .SWT Description .BLN sbrk() gets increment more memory. brk() sets the first unusable address to value. Both return a pointer to the beginning of the new memory area. settop() resets top of memory to value. .SWT Diagnostics .BLN NULL is returned if the memory requested is not available. There is no "shortened" return. Use settop() for this case. .SWT Bugs .BLN These routines only work on the RT11 library. Using them in RSX-mode will cause the job to abort with an IOT trap. .BLN These routines do not work together with alloc(). They should. .HLV 3 call Call (Fortran) subroutine from C .SWT Usage return_value = call(routine, count, &arg1, ... &argN); extern int routine(); /* PDP-11 function name */ int count; /* Number of arguments */ .SWT Description .BLN 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. .SWT The arguments are as follows: routine The name of the PDP11 routine to be called. count The number of arguments in the calling sequence. arg1 The first argument. For example: extern int sort(); int data_to_sort[NDATA]; int ndata = NDATA; call(sort, 2, &data_to_sort, &ndata); Note that, if the called function returns some other datatype such as a long, the routine and call() must be correctly declared: long call(); long myfun(); long larg; long result; result = call(myfun, 1, &larg); 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: .HLV 3 call Call (Fortran) subroutine from C .BLN 2 WARNING: watch out for trouble if the PDP-11 routine does any I/O. Floating-point data return has not been implemented. .HLV 3 callc Call C subroutine from (Fortran) program .SWT Usage integer callc ivalue = callc(routine, arg1, ... argN) .SWT Description .BLN User-callable interface between Fortran programs and subroutines written in C. .SWT 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 .BLN Untested. There will be I/O library conflicts since C files have not been initialized. .BLN The following problem will occur if a C subroutine is called from a Fortran main program: .BLN 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. .BLN What is worse is that there will be two main programs. .BLN It is therefore recommended that there be a C main program that calls Fortran subroutines that may, in turn, call C subroutines. .BLN The programmer can also define a dummy program that resolves the globals referenced by CSV$ or modify callc.mac to provide the necessary globals. .HLV 3 caller Return name of profiled caller .SWT Usage char * caller(); .SWT Description .BLN 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. .SWT Example: foo() { foobar(); } foobar() { extern char *caller(); printf("foobar was called by %s\n", caller()); } Bugs .HLV 3 calloc Allocate and Initialize Memory .SWT Usage char * calloc(n, m); /* NULL if no space */ .SWT Description .BLN 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. .BLN If the requested space cannot be allocated, calloc() returns NULL. .BLN See also the description of malloc(), realloc() and sbreak(). .BLN The space is returned by calling free(). .SWT Diagnostics Bugs .HLV 3 calltr Trace Path to the Caller .SWT Usage calltrace(outfd); FILE *outfd; .SWT Description .BLN 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: .SWT [ main sub1 sub2 ] .BLN 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(). .BLN A call trace will be printed on exit if tracing is enabled and the program aborts or calls error(). .SWT Bugs .HLV 3 concat Concatenate strings .SWT Usage char * concat(out, in0, in1, ..., inN, 0); char *out; char *in0, in1, ... inN; .SWT Description .BLN Concat concatenates the argument strings. It returns a pointer to the first byte of out. .SWT Bugs .HLV 3 copy Copy a given number of bytes .SWT Usage char * copy(out, in, nbytes) char *out; char *in; int nbytes; .SWT Description .BLN 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. .SWT Bugs .HLV 3 cpystr String copy .SWT Usage char * cpystr(out, in); char *out; char *in; .SWT Description .BLN Copy "in" to "out". Return a pointer to the end of out. This allows the following usage: .SWT char *ptr; char buffer[BUFSIZ]; extern char *cpystr(); ptr = cpystr(buffer, text); ptr = cpystr(ptr, more_text); .BLN The above sequence appends more_text to the copy of text already moved into the buffer. .SWT Bugs .HLV 3 ctime Convert Time Buffer to Ascii .SWT Usage char * ctime(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 .BLN Ctime() converts the time information in buffer such as returned by rtime() to a character string in the format: .SWT Sun Sep 16 01:03:52 1973\0 .BLN All the fields have constant width. .BLN Ctime(0) returns the current time of day, calling rtime() internally. .BLN 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. .BLN dayofweek() returns the day of the week (Sunday = 0) for the date information in the argument buffer. .SWT Bugs There is no range checking on the information passed. .HLV 3 envsave Multi-level function return .SWT Usage int * envsave(); envreset( fp, hval, lval ) int *frame; /* Frame pointer */ int hval; /* High-order return */ int lval; /* Low-order return */ Description .BLN These functions permit a multi-level return from a C function to one of its dynamic ancestors in the stack. .BLN 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(). .BLN 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. .BLN It is catastrophic to attempt to return to a function which has itself already returned!!! .BLN The following illustrates use of envsave() and envreset(): .SWT int *save_frame; process() { ... save_frame = envsave(); if (subprocess()) { /* * Success */ } else { /* * Failure */ .HLV 3 envsave Multi-level function return .SWT } } subprocess() { /* * Abort on error */ if (...) envreset(save_frame, 0) /* * Success */ return(1); } .BLN When subprocess() detects an error, it calls envreset() to return to the caller of process(), passing a "failure" flag. .SWT Bugs .BLN If the caller of envsave() has already returned, disaster will result. .HLV 3 error Error exit from C programs .SWT Usage error(format, arglist); /* Fatal error exit */ Description .BLN An error message is written to stderr and the program exits. If profiling was enabled, a subroutine call trace will be written to stderr. .BLN The "exit status" will be set to "error". .SWT Diagnostics Bugs .HLV 3 exit Exit from C programs .SWT Usage exit(); /* Exit, no return */ exits(status); /* Exit with status */ extern int $$exst; /* Exit status value */ .SWT 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. .BLN 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. .SWT RT11 RSX Meaning 1. 1. Success -- no message is printed 2. 0. Warning 4. 2. Error 8. 4. Severe error .BLN Calling exit() is equivalent to calling exits(1). Note that the program may also set a value into $$exst and exit via exit(): .SWT extern int $$exst; ... $$exst = 4; exit(); Diagnostics Bugs .HLV 3 fclose Close a currently-open file .SWT Usage fclose(iop); FILE *iop; .SWT Description .BLN Close the file. Returns 0 if ok, -1 if an error. The error code is saved in $$ferr. .BLN 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. .SWT Bugs .HLV 3 feof Test for end of file .SWT Usage feof(iop); FILE *iop; .SWT Description .BLN Return 1 if end of file on iop, else zero. .SWT Bugs .HLV 3 ferr Test for file error .SWT Usage ferr(iop); FILE *iop; .SWT Description .BLN Return 1 if an error has been seen on the indicated file. .SWT Bugs .HLV 3 fflush Flush output buffers .SWT Usage fflush(iop); FILE *iop; .SWT Description .BLN Flush output buffers. This routine actually does I/O. $$ferr is set if anything unexpected happens. .SWT Bugs .HLV 3 fget Get a record .SWT Usage fget(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; .SWT Description .BLN Read a record from the indicated file. Maxbytes is the maximum record size. .BLN On RSX, the file must have been opened using the "u" (user buffer) flag. .BLN On RT11, the file must have been written by fput(). .BLN The actual number of bytes read is returned. Use feof() to test for end of file. .SWT Bugs .HLV 3 fgets Read a line from a file .SWT Usage char * fgets(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; char * fgetss(buffer, maxbytes, iop); char *buffer; int maxbytes; FILE *iop; .SWT Description .BLN 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. .BLN Fgetss() is identical to fgets() except that the terminating newline is removed. (This is compatible with gets(), but is not compatible with the Unix standard library.) .SWT Bugs .BLN Note that fgets keeps the newline, while fgetss() and gets() delete it. To delete the newline after executing fgets(), execute the following: .SWT buffer[strlen(buffer) - 1] = 0; .HLV 3 flun Get logical unit number .SWT Usage flun(iop) FILE *iop; .SWT Description .BLN Return the logical unit number associated with the file. (On RT11, the channel number is returned.) .SWT Bugs .HLV 3 fmkdl Mark File for Deletion .SWT Usage fmkdl(iop); FILE *iop; .SWT Description .BLN fmkdl() closes and deletes the specified file. Returns 0 on success, -1 on error. .SWT Bugs .BLN 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. .HLV 3 fopen C library file opener .SWT 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 */ Description .BLN Fopen opens a new or existing file in the indicated mode: .SWT r Read the existing file sequentially w Create and write the file sequentially a Append to the file n Don't do newlines on each record. u RSX-mode: User does all buffering RT11-mode: use .ttyin and .ttyout .BLN Either "r", "w", or "a" must be given. "n" and "u" are optional. "n" should be given for "binary" files. The "u" flag is treated quite differently for RSX and RT11 modes. .BLN 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. .BLN On RSX, "n" or "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. .BLN On RT11, if fopen decides that the file being opened 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. .BLN 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. .HLV 3 fopen C library file opener .BLN 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 some other program has opened the channel, an E$$ILU error will be returned. .BLN The same file should 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 close and reopen the file before using fseek(). .BLN 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. .BLN 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: freopen loses any pending fwild/fnext status. .SWT Bugs .BLN The RT11 file system does not support files greater than 65535 blocks long. .BLN RT11 does not get the actual keyboard name of the console terminal, although this isn't too hard to do on RT11/RSTS/E. .BLN 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. .BLN The code is general, hence big. RSX users who typically overlay everything may find pleasure in breaking the code into many tiny modules. .HLV 3 fput Put a binary record .SWT Usage fput(buffer, nbytes, iop); char *buffer; int nbytes; FILE *iop; .SWT Description .BLN 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. .BLN On RT11, the file is only readable by fget. .BLN Nbytes is always returned. .BLN A call to ferr() after calling fput() is advised. .SWT Bugs .HLV 3 frec Return True if record-oriented file .SWT Usage frec(iop); FILE *iop; .SWT 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. .SWT Bugs .HLV 3 fseek File pointer reposition (seek) .SWT Usage fseek(iop, offset, param); FILE *iop; /* What device to seek */ long offset; /* New read position */ int param; /* Zero for abs. seek */ .SWT Description .BLN fseek() moves the i/o read pointer to the indicated position. The position must have been returned by ftell(). Param must be zero. The file/device must be seekable. .BLN fseek() returns zero if correct, EOF if an error occurs. If no error occurred, error and eof flags are reset. .BLN flseek() is an alternate entry with identical parameters and actions. .SWT Bugs .HLV 3 fspool Spool to Default Queue .SWT Usage fspool(fp); FILE *fp; /* Open file IOV */ .SWT Description .BLN 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. .BLN 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. .BLN 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. .BLN 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. .BLN 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(). .BLN If the file was opened by calling fwild()/fnext(), internal buffers will not be freed, allowing the program to call fnext() for subsequent files. .SWT Bugs .BLN On RSTS/E RT11 mode, error codes will follow the description of the spooling system function call. .HLV 3 ftell Tell file position .SWT Usage long ftell(iop); FILE *iop; /* What device to seek */ .SWT Description .BLN 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 shouls flush the current record before calling ftell(). (Flush() is a noop on RT11.) .BLN If reading lines of text, the correct sequence is: .SWT position = ftell(fd); if (fgets(buffer, sizeof buffer, fd) != EOF) { /* * 'position' locates the record * read by the call to fgets() */ } Bugs .BLN On RSX, the value returned is the position of the file pointer 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. .HLV 3 ftty Return True if terminal file .SWT Usage ftty(iop) FILE *iop; .SWT Description .BLN Return 1 if the file is a terminal-type device. In general, this means the user's command terminal. .SWT Bugs .HLV 3 fwild Wild-card file opener .SWT Usage FILE * fwild(name, mode); char *name; /* File to open */ char *mode; /* Open modes */ FILE * fnext(iop); FILE *iop; /* I/O pointer */ .SWT Description .BLN 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. .BLN Fnext() opens the first or next file which has been defined by a previous call to fwild(). If fnext() returns NULL, there are no (more) files that match the wild-card specification. .BLN fwild/fnext handle RSX file version numbers correctly on "native" RSX or VMS compatibility mode. For example, you 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 RSTS/E.) .BLN Note: if you call fclose(), all file name information will be lost. The following sequence illustrates how to use fwild()/fnext(): .SWT 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 */ if (count == 0) error("No matching files found"); Bugs .BLN Not (currently) implemented on RT11 modes. .BLN 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. .BLN 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: .SWT 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; .BLN 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(). .HLV 3 getchar Get characters .SWT Usage getchar(); getc(iop); FILE *iop; .SWT Description .BLN Getchar() reads one character from the standard input file. getc() reads one character from the indicated input file. .BLN Both return EOF on error or end of file. .SWT Bugs .HLV 3 gets Read a line from stdin .SWT Usage char * gets(buffer); char *buffer; .SWT Description .BLN 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. .SWT 2 Bugs .HLV 3 gettty Get control teletype name .SWT Usage gettty(buffer); char *buffer; .SWT Description .BLN Store the device name of the control teletype in buffer. Return 0 on success, -1 on error. .SWT Bugs .BLN On RT11 under RSTS/E, the actual keyboard number is not returned. (I dunno about "real" RT11). .HLV 3 getw Get a word .SWT Usage getw(iop); FILE *iop; .SWT Description .BLN 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. .SWT Bugs .HLV 3 iov I/O vector definition .SWT 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; /* Wild card lookup buf */ 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_BAD 0001000 /* Buffer needs filling */ #define IO_NOS 0000400 /* No newlines needed */ #define IO_UBF 0000200 /* User does buffering */ #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_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 */ .SWT Description .BLN 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. .BLN The RSX-mode IOV contains an entire file data block. 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 iovtoa() and to allow deleting files given the IOV pointer. .SWT The following files are defined here: stdin The standard input file. stdout The standard output file. stderr The error output file. Note: on RSX systems, stderr is opened on LUN 1. .BLN $$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: .SWT 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 .BLN 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). .BLN Error 7 is set if fopen tries to open a channel that is already in use. .SWT Bugs .HLV 3 iovtoa Convert file name to ascii .SWT Usage iovtoa(iop, buffer); FILE *iop; char *buffer; .SWT Description .BLN Convert the file name to Ascii and put it in the buffer. On RSX, the file name and file type are decompiled from the internal format. On RT11, the text that the user passed to fopen() is copied to the buffer. .SWT Bugs .HLV 3 isalpha Return TRUE if alphabetic argument .SWT Usage isalpha(c); int c; .SWT Description .BLN Return 1 if c is an alphabetic character, 0 otherwise. .SWT Bugs .HLV 3 isdigit Return TRUE if digit argument .SWT Usage isdigit(c); int c; .SWT Description .BLN Return 1 if c is an Ascii digit, 0 otherwise. .SWT Bugs .HLV 3 islower Return TRUE if lower-case alphabetic argument .SWT Usage islower(c); int c; .SWT Description .BLN Return 1 if c is a lower-case alphabetic character, 0 otherwise. .SWT Bugs .HLV 3 isupper Return TRUE if Upper-case alphabetic argument .SWT Usage isupper(c); int c; .SWT Description .BLN Return 1 if c is an Upper-case alphabetic character, 0 otherwise. .SWT Bugs .HLV 3 itoa Integer to Ascii .SWT Usage itoa(value, string); int value; char *string; .SWT Description .BLN itoa converts the value to a (signed) decimal string. The string is null-trailed. .BLN Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%d", value); .SWT Bugs .HLV 3 itoa8 Convert integer to octal Ascii .SWT Usage itoa8(value, buffer); int value; char *buffer; .SWT Description: .BLN The value is converted to octal and stored in the buffer. .BLN Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%o", value); .SWT Bugs: .BLN This routine does not generate leading zeros. .HLV 3 itoax Convert an integer to hexidecimal Ascii .SWT Usage itoax(value, buffer); int value; char *buffer; .SWT Description: .BLN Convert the integer to hexidecimal ascii. The string is null-trailed. Values from 10 to 15 (decimal) are represented by "A" to "F". .BLN Note that the result can be computed (more flexibly) by executing sprintf(buffer, "%x", value); .SWT Bugs: .HLV 3 malloc Allocate and free memory .SWT Usage char * malloc(size); /* NULL if no space */ unsigned size; /* Number of bytes */ mfree(p); free(p); char *p; /* Was allocated */ .SWT Description .BLN 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. .BLN free() and mfree() return a buffer to free space. Nothing is returned. .BLN See also the description of realloc() and sbreak(). .SWT Diagnostics .BLN 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. .SWT Bugs .HLV 3 memdmp Dump memory and registers .SWT Usage memdmp(start, end); /* Memory dump routine */ char *start; /* First to dump */ char *end; /* Last to dump */ regdmp(); /* Register dump */ .SWT Description .BLN Dump registers and/or memory. All registers are preserved. .BLN If memdmp is called with a zero argument, the stack will be dumped. .BLN Note that this routine does not use the C I/O library. .SWT Bugs .BLN Condition codes are not preserved. .BLN On RSX, these routines require that the terminal has been assigned as logical unit number 1. .HLV 3 msg Print a message on the console .SWT Usage msg(text) char *text; .SWT Description .BLN Print a message on the console terminal. This routine does not use the standard library. Return: all registers are preserved. .SWT Bugs .BLN On RSX, this routine requires the command terminal having been assigned as logical unit number 1. .HLV 3 peek Peek at a location in RSTS/E .SWT Usage peek(location) int *location; .SWT Description .BLN Peek to a location in the RSTS/E monitor. .BLN The job will be aborted with a BPT if not running under RSTS/E. .SWT Bugs .HLV 3 printf Formatted print routine .SWT Usage printf(format, arg1, ...); char *format; fprintf(iov, format, arg1, ...); FILE *iov; char *format; sprintf(buffer, format, arg1, ...); char *buffer; char *format; .SWT Description .BLN 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. .BLN 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. .BLN Each conversion specification is introduced by the character %. Following the %, there may be .AND an optional minus sign "-" which specifies left adjustment of the converted argument in the indicated field. .AND an optional digit string specifying field width; if the converted argument has fewer characters than the field width, it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width. If the field width is given as '?', the next argument is used. .AND an optional period "." which serves to separate the field width from the next digit string; .AND 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 given as '?', the next argument is used. .AND a character which indicates the type of conversion to be applied. .HLV 3 printf Formatted print routine .SWT 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. 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. 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. g Floating point of some sort. 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); } 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 .HLV 3 printf Formatted print routine .SWT 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 haven't been written yet. .HLV 3 profile Print profile information .SWT Usage $$prof(); extern int $$prnl; extern char *$$pfil; .SWT Description .BLN $$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 profile output may easily be sorted either by function name or by frequency count. Bugs .HLV 3 putc Put one character to a file .SWT Usage putchar(c); char c; putc(c, iop); char c; FILE *iop; .SWT Description .BLN 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 .HLV 3 puts Put a line to a file .SWT Usage puts(s); char *s; fputs(s, iop); char *s; FILE *iop; fputss(s, iop); char *s; FILE *iop; .SWT Description .BLN 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 .HLV 3 putw Put a 16-bit word to a file .SWT Usage putw(word, iop); int word; FILE *iop; .SWT Description .BLN putw() writes one word to the indicated file. It returns EOF on error, 0 on success Bugs .HLV 3 r50toa Convert Radix-50 to Ascii .SWT Usage r50toa(buff, r5vec, r5cnt); char *buff; /* Output text buffer */ int *r5vec; /* Input rad50 buffer */ int r5cnt; /* How many rad50 words */ .SWT Description: .BLN Convert r5cnt words of radix 50 data to Ascii. The output buffer is not null-trailed. All letters will be in upper-case. Bugs .HLV 3 rand Random number generator .SWT Usage rand(max) int max; extern long seed; /* Random number seed */ .SWT Description .BLN Generate a pseudorandom number. If max is zero, return a number in the range 0 .. 32767. If max is non-zero, return mod(number, max); 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 .HLV 3 realloc Reallocate memory .SWT Usage char * realloc(buff, size); char *buff; /* Buffer from malloc() */ unsigned size; /* New size for buff */ .SWT Description .BLN 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(). Diagnostics The program will abort if buff is not the address of a buffer allocated by malloc() or calloc(). Bugs .HLV 3 rewind Rewind a file for re-reading .SWT Usage rewind(iop); FILE *iop; .SWT Description .BLN 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 .HLV 3 rtime Convert Date and Time .SWT Usage rtime(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; .SWT Description .BLN Stores the current time of day in the buffer. The format is compatible with the RSX11-M GTIM$ executive service. Bugs .HLV 3 sbreak Allocate memory from operating system .SWT Usage char * sbreak(amount); int amount; .SWT Description .BLN sbreak() 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 .HLV 3 setcc Trap Control/C (RSTS/E RT11 mode only) .SWT Usage setcc(function); extern int function(); .SWT Description .BLN 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. .HLV 3 sleep Delay job a given number of seconds .SWT Usage sleep(delay); int delay; .SWT Description .BLN Sleep a specified number of seconds. Bugs .HLV 3 strcmp String comparison .SWT Usage strcmp(a, b); char *a; char *b; .SWT Description .BLN Compare two strings, return -1 a < b 0 a == b +1 a > b Bugs .HLV 3 strcpy String copy .SWT Usage char * strcpy(out, in); char *out; char *in; .SWT Description .BLN Copy "in" to "out". Return out. Bugs It might be more useful if it returned out + strlen(in). (See cpystr()). .HLV 3 streq String equality .SWT Usage streq(a, b); char *a; char *b; .SWT Description .BLN Return TRUE if the strings are equal. Bugs .HLV 3 strlen String length .SWT Usage strlen(s); char *s; .SWT Description .BLN Return the length of the argument string. Bugs .HLV 3 swabb Byte swap (argument is a buffer pointer) .SWT Usage swabb(buffer); char *buffer; .SWT Description: .BLN Return buffer[0] and buffer[1] as a byte-swapped integer. Buffer need not be on any particular byte or word boundary. Bugs .HLV 3 swabi Byte swap, (argument is an integer) .SWT Usage swabi(value); int value; .SWT Description .BLN Return value byte-swab'ed. Bugs .HLV 3 time Time of day .SWT Usage long time(0); long time(tloc); long *tloc; .SWT Description .BLN 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. See rtime() for a more flexible routine. Bugs The Unix time function returns the time since 00:00:00 GMT, Jan 1, 1970, measured in seconds. This function returns the time of day in seconds. .HLV 3 tolower Convert upper-case alphabetic to lower-case .SWT Usage tolower(c); int c; .SWT Description .BLN If c is a upper-case alphabetic, return it's lower-case equivalent. Otherwise, return c. Bugs .HLV 3 toupper Convert lower-case alphabetic to upper-case .SWT Usage toupper(c); int c; .SWT Description .BLN If c is a lower-case alphabetic, return it's upper-case equivalent. Otherwise, return c. Bugs .HLV 3 trace Profile support entry module (with trace) .SWT Usage #include extern FILE *$$flow; $$flow = fopen("trace.out", "w"); /* or $$flow = stderr; to trace to the console */ ... $$flow = NULL; /* Turn off flow trace */ .SWT Description .BLN This module is called whenever a function that was compiled with the profile option is executed. It checks that the stack will remain above 600 octal when the function executes and optionally prints a flow-trace. If $$flow is set to a file descriptor, the function name, location the function is called from, and the calling environment, are printed on each call to a function compiled with the profile option. The output format is: function_namecallerenvironment Where function_name is the name of the function being called, caller is the address of the calling program (actually, the return address), and environment is the R5 argument pointer (for local addressing within the 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. Bugs .HLV 3 traps Trap handlers .SWT Usage Internal $$sstt:: ; RSX synchronous trap ; vector $$t410:: ; RT11 Entry after traps ; to vectors 4 and 10 .SWT Description .BLN 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. 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. 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 Currently may loop if a trap occurrs within the trap handler. .HLV 3 traps Trap handlers .SWT Internal Don't forget to handle floating-point when it's implemented. .HLV 3 ungetc Push back a byte onto an input file .SWT Usage ungetc(c, iop); char c; FILE *iop; .SWT Description .BLN Push one character back on the indicated stream. Abort by executing a BPT instruction if more than one character is pushed back. Bugs .HLV 3 unwind Execute non-local goto .SWT Usage setexit(); unwind(); .SWT Description: .BLN 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 .HLV 3 wdleng Expensive way to say sizeof(int) .SWT Usage wdleng() .SWT Description .BLN Return word length. Bugs This may be replaced by: #define wdleng() (sizeof (int)) .HLV 3 wrapup Dummy routine called on exit .SWT Usage wrapup() .SWT Description .BLN 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 .HLV 3 zero Clear a block of memory .SWT Usage zero(addr, nbytes); char *addr; int nbytes; .SWT Description: .BLN Clear the block of core. No value is returned. Bugs